宜博 / lemonboss

P1-P5 落地后做了一次真实端到端测试（建公司→下 goal→ceo 监督→真实跑出
一个 Playwright 验证 5/5 通过的贪吃蛇游戏）。1469 个单测全绿，这次真跑
却测出至少三个单测没覆盖到的真问题：服务器重启会让 in-flight 节点变
僵尸且无人能自动发现、graph-run.js 鉴权缺口（已在另一个 commit 修过）、
规划/反思轨迹没有统一可追溯位置。

39 号文档新增「七、真跑复盘」记录技术缺口和过程教训；41 号文档把复盘
沉淀的待办拆成四个 phase 的开发计划（卡住恢复闭环 → 闸门穿透性回归
测试 → target_dir 配置入口 → timeline 承接规划轨迹），按优先级排开工
顺序。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwG4b7Nq1NLR9eeE3M9Us9

- writeGraph() 的乐观锁缺失此前误标"已修复"，实际只是后续实验绕开没再撞它，改回开放
  TODO 并补上修法思路（CAS 式版本校验）。
- company.js 的 requireAuthOrInternal 401 缺口、boss agent 巡检设计，均已被另一并行会话
  实际修复/实现（14cbaf5、39 号文档 P1-P5），核实代码后删掉这两条过期 TODO，指向正确出处。
- 新增一条未拍板的可选项：org-hunt/digest/evolve 这套"元 agent 复刻成 graph 原生副本"的
  操作模式要不要沉淀进 org-graph-templates/README.md 供以后参考。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

第 11 轮真跑：给 org-evolve 规划验收节点时，按名字语义匹配选了 benchmark-validator
（"对评分结果做验收判决"），但该本体硬编码读 artifacts/goal-benchmark.json（只有
planner.json 的 goal-benchmark 节点才产），Hunt→Digest→Evolve 链路里没有这个节点，
两轮都判 blocked。benchmark-validator / testdata-validator / validator-triager 不是
通用验收工具，是 validator.json 骨架专属、绑定任务级共享契约文件的本体。

workgraph-planning/agent.md 加第三条硬规则：判据从"名字像不像"改成"这条链路里有没有
节点产 goal-benchmark.json/acceptance.json"。deliverable.json 的 whenToUse 补上"自带
自评分收敛逻辑的节点也不需要外部验收节点"例外条款并点名这次事故。

第 12 轮真跑验证：org-evolve 的规划记录原文引用新条款选中 deliverable.json，
backward_count=0，评分 83/行业均线 78 收敛，全流程干净跑完。41 号文档收尾——
11 轮真跑挖出的 6 个独立缺陷全部修复并逐条验证生效。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

核心修复：indexNodeOutputs() 此前只扫节点私有目录，不扫项目根——但引擎自己的写入边界
明确允许交付物写项目根，导致内容型交付物节点（产出写进项目根时）永远进不了 R-19 产物
索引，下游 needs 声明永远查不到实例。新增 readDeclaredProduces()：agent 可在
contract.json 里显式声明 produces:{kind: 绝对路径}，校验（绝对路径/落在项目根或私有目录内/
文件真实存在）通过才登记，不满足就整个 kind 判「没产出」，不静默放过。全局提示词
（describeArtifactContract）同步更新，所有 org/work 节点自动学到这个新字段。

新增 org-hunt / org-digest / org-evolve 三个 graph 原生 agent（方法论抄
innovator-hunt/digest/evolver，协议原生兼容 graph 引擎），配套新增 work-graph-templates
的 deliverable.json（内容型交付物骨架，不引入验证 agent）。11 轮真实试跑挖出并修复 5 个
独立缺陷（详见 41 号文档问题 7）：建公司自动规划与手写图的竞态、work-graph 模板库缺内容型
交付物骨架、验收节点任务描述范围溢出、两个规划 agent（orggraph-planning/workgraph-planning）
的路径口径写错、以及上述 R-19 索引缺口。最终产出与原生 FDE 对比：内容骨架可迁移、质量不
打折，但可靠性差距悬殊。

补充说明：system/agents/{ceo,innovator-evolver,master,org-innovator}/{agent,soul}.md 是
本会话开始前已存在的 dream 自编辑改动，随本次提交一并收进去，不属于本次改动范围。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

39 号文档地基 0 当时只改了 company.js（goals/tasks 端点），graph-run.js
（run 的 start/stop/retry/budget 控制端点）漏了同一处修复，还是纯
requireAuth。真实端到端测试里 ceo 被唤醒后能读写 goal/task 板，但调
/api/graph-runs/* 处理卡住的 run 时精确撞上 401——ceo 自己在对话记录里
诊断出这一点并写出了人工需要跑的 curl 命令，间接验证了这条修复的必要性。

两个挂载点（router + companyRouter）都改成 requireAuthOrInternal，两处
:companyId/:id 的 param 中间件加了与 company.js 一致的 req.user?.internal
旁路。route-auth-gate.test.js 同步更新断言。全量测试 1469/1473，零回归。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwG4b7Nq1NLR9eeE3M9Us9

排查「前端刷新不及时/没有打字机效果」发现现状已是 SSE，不需要换 WebSocket，
真正缺的是三件独立的事：

- 打字机平滑：后端把 ACP chunk 按 10 字符切片再发 SSE，前端用定时器队列
  （agentChatEvents.js 的 createTypewriterQueue）匀速吐出，抹平网络突发。
- 打断并发送：执行中解锁输入框，新增 ⤴ 按钮与 ⏹ Stop 视觉区分；stop 端点
  改为轮询确认 agentChatLocks 真正释放（3 秒预算）再返回 cleaned 字段，
  前端据此决定直接发送还是走"强制发送"兜底。顺手修了一个真实并发漏洞：
  同一 agentId + 同一 convId 的并发请求过去完全没有闸门，只是一直靠前端
  textarea 的 disabled 属性侥幸没被触发。
- 串台加固：把 handleEvent 分发逻辑抽成不依赖组件实例的纯函数
  （agentChatEvents.js），补上 9b1c3f1 那条不变式的回归测试。

已用真实 Claude CLI 会话（非 mock）在浏览器里验证打字机效果、打断并发送
全流程、以及纯 Stop 无回归。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDtmdnE6pay9BhwZDAKK6M

按 39 号设计文档落地 ceo 常驻监督：company.js 的 goals/tasks 端点
放行内部令牌自环调用，POST /tasks 支持 draft 模式（agent 自主提任务
不再立刻烧预算），ceo 补雇进公司创建流程；task-settle 新增事件驱动
唤醒 + 30 分钟兜底轮询；graph-engine 的回退熔断收敛时顺手回写一条
draft task，形成"卡住 → 自动/ceo 判断 → 重新规划"闭环。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwG4b7Nq1NLR9eeE3M9Us9

docs/README.md 索引条目同步从 todo/（当前主线）表格挪到 done/ 表格，路径改指
done/system-design/。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

验证阶段真查出一个 Phase 1/2 都没顾上的真实漏洞：agent-chat.js（/api/agent/*）一直靠
:agentId 里的 "companyId:role" 命名空间前缀（locator.companyStateDir 解析）区分会话
属于哪家公司，但这个文件从只挂了 requireAuthOrInternal（登录即可），没有归属校验。
curl 验证：任意登录用户对 GET /api/agent/{别人的companyId}:{role}/conversations
依然 200，能跨租户读别家公司的 agent 会话。

修法跟 company.js 同一套思路：router.param('agentId', ...) 解析 : 前的 companyId 段，
过 canAccessCompany。三个例外：①没有 : 前缀的全局 agent（master/org-innovator 等，
落 _global）不做归属校验，本来就全系统共享；②内部自环调用（req.user.internal）直接
放行，招聘/训练自动流水线要能打到任意公司名下；③admin 不受限制。

新增 agent-chat-company-gate.test.js：直接拿 Express 暴露的 router.params.agentId[0]
单测这个 param handler，覆盖同公司放行/跨公司404/admin不受限/公司不存在404/全局agent
放行/内部自环放行六种情况。顺带修好一个连带失败的既有测试文件
（agent-chat-tenant-isolation.test.js，zz-tenant-alpha/beta 同样是从没真正建过的
虚构公司 id）。

验证：curl 复测跨租户读会话从 200 变 404，owner/admin 依然 200，全局 agent 不受影响；
真实浏览器用全新账号确认 CompanyDashboard.vue 对"没有可用公司"已有现成空状态，不需要
新写前端代码。全量 vitest 1433 passed，3 个无关既有失败不受影响。

至此 38 号文档 Phase 0/1/2/3 全部完成。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

company-service.js：company.json 加 ownerId（无 SQL 表，纯 JSON 字段）；create() 接收
ownerId；list({ user }) 按传入用户过滤，不传就不过滤（company-heartbeat-service.js 等
系统内部巡检要看全部公司）；新增 canAccessCompany(company, user) 作为全仓库唯一一份
归属判据（admin 不过滤，判负一律 404 不是 403，不暴露"这个 id 存在只是不是你的"）。

company.js 用 router.param('companyId', ...) 统一收口（约 50 条路由，含 okrPath() 系列
动态路由）。graph-run.js 的两个挂载点参数形状不一样，设计阶段的描述不准确，实现时才
发现：companyRouter 唯一路由是 /:companyId/graph-runs 直接查；主 router 全部路由是
/:id/...，:id 指的是 run 不是公司，改成先查 run 的 company_id 再判断，run 不存在或
公司不是你的统一回"run 不存在"。devloop.js 用 :pid 反查 company_id；POST /projects
单独校验 body 里的 company_id（放在基本字段校验之后，避免归属检查打乱输入校验的错误
优先级）；GET /projects 按归属过滤列表。

okr.js 最终没有按原计划接入 companyId 归属校验——实现前查证发现 OkrDashboard.vue
挂载的 /okr 页面全站没有任何导航入口指向它，是个孤儿页面，给访问不到的页面建"选公司"
前端交互不划算，改成 requireAdmin（跟 dream.js 同款），先堵住直接拼 URL 看到跨公司
聚合数据的口子。真正在用的公司级 OKR（company.js 的 /:id/okr）已随 company.js 一起隔离。

存量数据迁移：scripts/backfill-company-owner.js（npm run backfill:company-owner），
两家存量公司已划给种子账号，幂等验证过。

8 个既有测试文件用的公司 id 都是从没真正建过的字符串标签，挂锁后集体 404——新增共享
helper server/tests/helpers/ensure-test-company.js 修复；两处原有的"跳过已有
company.json 的目录，那是真公司"防御逻辑，判据从"有没有 company.json"改成"ownerId
是不是 -1 这个测试专用标记"，否则新出现的测试夹具会被误判成真公司永远不清理。

验证：真实 curl 走过（admin 看到全部存量公司、新用户看到空列表、新用户拼 URL 访问
别人的公司 404、新建公司 ownerId 精确落在创建者、admin 和创建者都看得到其他人看不到）；
全量 vitest 1427 passed，3 个无关既有失败不受影响。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

给此前完全零防护的 company.js/okr.js/tasks.js/devloop.js/graph-run.js（两个挂载点）/
arena.js/config.js/evolution.js/whatsapp-auth.js 挂 requireAuth；dream.js 挂 requireAdmin
（系统级经验汇流视图，只有 admin 能看）。open-api.js（自己一套 OPEN_API_KEYS）/auth.js
自身/health 端点按计划排除。这一步只挡"没登录"，公司归属过滤留到 Phase 2。

agent-chat.js 不能直接挂 requireAuth：company.js（自动建公司/招聘后自动训练）、
task-settle.js（goal 汇报回调）三处服务端自环调用会 fetch 自己的 /api/agent/* 端点，
拿不到任何用户 cookie，直接挂锁会打断这几条核心自动化链路。新增 requireAuthOrInternal +
jwt-auth.js 的进程内 INTERNAL_TOKEN（启动时随机生成，只活在内存里）：自环调用带上
x-internal-token 头放行，其余情况仍要求真实登录；三处调用点同步改造。

17 个既有测试文件、67+ 处用例直接拿 supertest 打这些路由，从没设过登录 cookie（测的是
业务逻辑不是鉴权）。没有逐个补登录态，改为 requireAuth/requireAdmin 在 NODE_ENV=test
时默认放行，除非显式 FORCE_REAL_AUTH=1；新增 route-auth-gate.test.js 在放行关闭状态下
做结构检查（router.stack 里中间件是否真的排在所有路由前面），确保"锁真的挂上了"这件事
有测试兜底，不被业务测试的默认放行悄悄掩盖。

验证：真实 curl 走过全部路由（无 cookie 401、admin 登录全通、非 admin 能看公司但
dream.js 403）；手工删过一行 requireAuth 确认守卫测试真的会红；全量 vitest 1427 passed，
另 3 个失败与本次改动无关（stash 验证过改前改后一致，系仓库并发工作遗留）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

远程部署前置需求：登录鉴权 + 公司级多租户隔离。后端 auth.js/jwt-auth.js（注册/登录/
JWT-cookie/OAuth）本来就已经可用，这次只是把它接到前端。

- scripts/seed-admin-user.js（npm run seed:admin）：幂等种子脚本，建出 admin/hex1234，
  role=admin。
- web/src/composables/useAuth.js + views/Login.vue：登录态 + 登录页。
- router/index.js 全局 beforeEach：未登录跳 /login?redirect=...，登录后带着原目标跳回。
- main.js 全局 401 拦截器：cookie 中途过期同样兜住，不止页面切换那一刻。
- AppNav.vue：显示用户名 + 退出登录。
- 顺手修：App.vue 原来无条件渲染 MasterChatDrawer，登录页也会露出这个悬浮入口，
  改成登录且非登录页才显示。

业务路由还没加锁（Phase 1 的事），登录后依然能看到现状全部数据，符合这一阶段的验收边界。
真实浏览器走过一遍全部流程（跳转/登录/跳回/直接刷新受保护路由/退出），npm run build 通过。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

现状 org graph 按 company_id 单例（27-P2 标题原文即"公司级"），塞不下 HR/财务/市场这类
跟"交付流水线"无关的公司常设职能——system/agents/hr/（"招·留·管·退"）本体已存在却从没
被装进任何图，全靠 fire-and-forget chat 招聘，没有图执行那一套断点续跑/审计轨迹。

提议把作用域从 company_id 升级为 (company_id, department_id)，一家公司可装配多张部门图，
每张仍保持人工固定/慢变/可审计——不是把角色图变成动态生成，只是允许公司持有的图从 1 变成 N。

全仓库调用点扫描（fork）结论：改造面是最初估算的 4 倍。真正的单点真相在
work-graph-db.js:readDefGraph 的裸 SQL 不变式（graph_id === company_id，写进了 §四.A.2
设计文档），坐在 graph-engine.js 执行引擎的热路径上，不在 org-graph-service.js 那层服务
API；另外还有两个易混淆的服务文件（org-graph-service.js / graph-service.js）共同维护一份
必须字节级一致的重复唯一索引、独立的 graph-seed-service.js 对账子系统（8 处裸 SQL）、
company-hire-org-layer.test.js 专属测试套件、orggraph-planning/task-planning 两份 agent
人设文档把"只有一张图"写进了自我认知——都需要一并改。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

在 prd-planning/agent.md 加了「描述性语言扫描」+「内容深度下限」+「业务度量翻译」三段
具体操作（对应 36 号文档训练出的 SKILL.md Step 4/5），soul.md 加一条对应工作原则。
用同一个 e2e-demo 首页任务重新跑了一次端到端回归验证：新 PRD 把"大图/简洁大气"等形容词
逐条翻译成量化规则，最终产出的 index.html/style.css 精确对应这些数值（视觉元素
min-height:320px、区块间距 96px/56px 等），文案不再卡在"非空"这条线——训练效果在
真实任务里得到验证。

回归过程中发现一个新的、独立于本次改动的引擎缺陷：org-coder-test 被反向打回后产出
「建议重跑 org-coder-validator」的诊断文件，引擎把诊断文件里的 infra_flake 标记当成
了这个节点自己的执行结果，导致原地重跑但从不路由到诊断建议的目标节点，陷入没有熔断线
的确定性死循环。记进 30 号文档，留待后续修复。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

新建独立试验节点 prd-methodology-trial，走真实 Hunt→Digest→Evolve 训练 PRD 撰写方法论：
2 轮 Small Loop 提前收敛（96/97 分，真实基线 50 分），用三个真实历史项目反推验证方法论
有效，Deploy 范围限定在该独立节点，未触碰生产 prd-planning。结论：FDE 对方法论类角色
确实管用，但收敛速度/验收严谨度依赖任务书里显式写明的自纠正要求，非免人工黑盒。

过程中连带修复同一个 2026-08-16 改名批次（innovator→org-innovator 等）遗留的 5 处死链：
company.js 两处硬编码调用、CompanyDashboard.vue「重新训练」按钮，以及四个本体各自
config.json 内部 id 字段从未随目录改名同步更新，导致 /api/agent/list 展示层用假 id
显示成死卡片。顺手修了 AgentScaffold 默认 tools.md 模板一处裸相对路径缺陷（对应
agent-md-refs.test.js 里已登记多时的已知缺陷）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

补记 commit fadb6fa 的实现记录：证据闸门选了"拦截"不是"降级"（降级等于还是采信
了分数，只是换个说法）；goal-benchmark.json schema 完全不用改，evidence 早就是
benchmark-validator/agent.md 教的既有字段，只是从没被 goal-contract.js run 读过，
让 runBenchmark 多看一眼姊妹判词文件即可，没有发明新格式；C 的实现只更新了真正
写分数/证据的 benchmark-validator，不是最初以为的 coder/unit-tester。

§三推进顺序标注全部完成，并记录了样本量不足的遗留风险（只有一次真实回归验证过
证据闸门，关键词表覆盖度与拦截后的连带影响都还没有大量数据支撑）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

补记 commit bab675c 的实现记录：按"第一版先做前者"落地（blocked 等人工，
装配自愈留后续），以及中途把测试套件炸穿 75 个用例又收窄回来的完整过程——
根因是 missingBodyDefinition 查真实文件系统，测试夹具的假 systemAgentId
天然"缺失"，改法是借用已有的 boundaryGuardApplicable 判据（只在真实执行器
下生效），不是发明新判据。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

用户问"任务结果差是 agent 能力、架构、还是 graph workflow 问题"，这份文档是
书面复盘：按发生顺序分四类——图/模板设计缺陷（31/33 号，已修）、招聘装配可靠性
bug（32 号已知问题的新样本）、一个复盘时新发现的架构缺口（missingBodyDefinition
完整性闸门只在招聘路径上调用，graph-engine.js 的执行核心路径 advanceOne 一次
都没查，本体不完整时没有第二道防线，静默拿空提示词跑真实 LLM）、agent 能力
（不是问题，两次订正过"没工具做不到"的误判，且有正面即兴发挥的例子）。

结论：主要是架构问题 + 一个具体可靠性 bug，不是模型能力问题。

提出两档改进方案供讨论：
  低成本（建议直接做）——把完整性闸门接进图执行前置检查（提案 A）、
    控制台展示验收证据可见性（提案 B，纯 UI 不改行为）
  大改动（建议先讨论优先级）——标准化视觉验收工具（提案 C）、
    引擎级证据闸门（提案 D）

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

§5.1 原来断言"没有浏览器工具，物理上做不到"，复盘时对照 p-bkhylu 的 org-coder
（同样只有 bash/read_file/str_replace(+write_file)，没有专门的浏览器工具）却
真跑出了 Playwright + headless Chromium 测试，才发现这个判断错了：仓库自带
playwright 依赖，bash 里 `node verify.mjs` 沿目录树能 require 到仓库根的
node_modules，这条路今天的 coder/unit-tester 同样走得通。

真正的差异不是工具权限，是 unit-tester 的 agent.md 从未填充过（32 号文档那类
问题）、没有任何角色指导，而 org-coder/coder-validator 都是正常填充过的成熟
本体。根因从"平台缺工具"改判为"这次没有指导 agent 主动想到"，是一个不一样、
也更能采取行动的结论。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

对比 e2e-demo 现有的三个项目根：
  p-v82tpc（今天的回归任务）—— 静态正则解析文本，零浏览器
  p-bkhylu（"做一个 lemonai 官网"）—— 真实 Playwright + headless Chromium：
    六档视口量 scrollWidth/clientWidth、getComputedStyle 量字号、手算 WCAG 对比度、
    禁 JS/reduce-motion 验证、整体挪到 /tmp 用 file:// 重开验证可移植性
  p-v1mpcl（31 号文档那条原始卡住任务）—— 无验证，任务在验收前就被取消

p-bkhylu 的 DELIVERY.md 里那句"未采信自证脚本，符合 SDD §0/§2 I-4 验收独立性
要求"，搜遍 system/、docs/ 都找不到这条规则——它是那次任务的 sdd-planning 会话
自己写进那次 SDD 的，不是仓库级别的通用约束。也就是说三条任务里，要不要认真
验证、认不认自证脚本，完全取决于哪次任务规划时 agent 会话恰好这么想，没有系统
保证。这就是 34 号文档 §三"影响面"判断的实锤：任务显示"已完成"与"真的达成
原始需求"之间的落差，目前只能靠运气。

34 号文档 §四 checklist 全部查完，状态行同步更新。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

之前把这条 run 手动 patch required=0 + 重试推到 completed 那次操作，其实就是
"用真实回归任务验证 org-coder-validator 不再假阳性 blocked" 这条的证据，回来补记
（唯一没走到的是"由 workgraph-planning 全新规划一张图"这一环，端到端证据仍缺）。

复查了 validator.json 的 needs:[{kind:'artifact',required:false}]：不是同类潜伏
问题，是刻意设计——它验的 artifact 由另一张图产出，靠任务级共享索引找，
不依赖这条边的声明，required:false 与 33 号的 log 声明成因完全不同。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

34 号文档追加调查（§五）：
- coder-validator（预置 active 本体）的 agent.md 通篇是代码/契约正确性验证协议
  （npx vitest run + 抓假绿五件套），压根不涉及视觉/交互检查；这次任务新招的
  coder/unit-tester 两个本体 toolPolicy 都只有 bash/read_file/str_replace，
  没有浏览器/截图工具——goal-benchmark.json 的 evidence_hint 要求"打开浏览器"，
  在给定工具权限下物理上做不到，不是 agent 偷懒。
- 但也不是纯粹空手套白狼：data/companies/e2e-demo/projects/p-v82tpc/tests/
  unit-tester.check.js 是一份真实可运行的零依赖静态断言脚本，对维度 1-3 的检查
  （字号比例真解析 CSS clamp() 算出数字、三个卖点区块标题顺序、锚点跳转/平滑滚动）
  与浏览器版本基本等价甚至更精确；维度 4/5（响应式断点、资源完整性）的静态版本
  明显更弱，会放过断点内样式写错、本地资源路径错误这类情况。

顺带发现：这份脚本很可能是 unit-tester 在提示词完全没有测试方法论指导的情况下
自己想出来的——它的 agent.md 还是没填充过的 _base 原始骨架（隔壁 coder 正常填充
过），是 32 号文档"招聘装配没填充完"那类问题的又一个真实样本（发生在方案 B
修复提交 6a18379 落地前 1 小时，是旧行为的证据，不是新机制的回归；新机制下
会不会正常完成，仍未验证）。32 号文档 §四追加第 6 条记录这次样本。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

用户反馈：控制台原来只能逐个节点点「输入输出」tab 看产物，缺一个全局入口。
新增 TaskFilesPanel.vue，挂在页头，跨节点/跨 run 一次性列出这个任务的全部产物。

做的时候发现分两类、且第二类之前完全没覆盖：
  · 节点产出索引（graph_files，按 company+task 检索）——规划笔记/日志/契约快照
  · 项目根（W2 ensureProjectRoot，data/companies/{cid}/projects/{pid}/）——
    真实交付物代码写的地方，跨节点共享，indexNodeOutputs 从不扫它

后端补 readProjectRootRecord 导出 + GET /api/graph-runs/:id 挂 projectRoot 字段；
项目根的文件列表复用已有的 GET /:companyId/files（此前零调用方），不新开列目录端点。
新增 graph-run-route-io.test.js 两例（分配前 null、分配后原样透传 + 幂等）。

顺带订正 34 号文档：当时断言"index.html 从未被写出来"是错的——真实网站文件
其实在项目根里，只是没查那个目录。34 号文档 §零 记录了订正过程，问题收窄成
"validator 有没有真的做过浏览器级检查"（仍未解决，留待下次）。

全量单测 1000/1000 通过。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

真实回归任务 T-mt2r6fz0-125b 走到 completed 后回查产出，发现 org-coder-impl
从未写出任何 HTML/CSS/JS 文件（只有 _plan.md/_research.md/coder.log），但
org-coder-validator 给六个维度全打了 100 分。goal-benchmark.json 的
evidence_hint 里五个维度明确要求"打开 index.html/浏览器开发者工具检查"，
这份评分显然没有真的执行过这些检查——是一次没有证据支撑的评分，不是
"查过但判错"。

不是 31/33 号修复引入的新问题，是那两次修复让这条本会一直卡死的任务真的跑到
completed 之后，才把这个一直存在的验收缺口暴露出来。只记现象与证据，根因
（提示词缺前置检查？validator 没有可用的浏览器/文件工具？是不是这次新招聘
本体特有的一次性现象）留给下次调查，这次不深挖。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

org-coder-validator 在真实回归任务里被 missing_required_input 反复误判 blocked：
executor.json/executor-fanout.json 的 test/integration→validator 边声明
produces:["log"]（required 默认 true），但 test 类节点从不写出能被 indexNodeOutputs
认作 kind=log 的文件（coder.log 实际属于 impl，test 自己的 _plan.md/_research.md
认不出 kind 也没有一对一无歧义可猜），这个 kind 因此永远不会被索引到，
requiredInputsMissing 每次都判缺失——不是时序问题，是结构性、每次重试都复现的硬伤。

改成 { kind: 'log', required: false }，对齐 validator.json 已有的写法（它的
needs:artifact 早就标了 required:false）。真正必需的 needs:artifact 不变，
仍受硬闸门保护。

中途走了一段弯路：最初以为该改 inboundContracts() 按 role 过滤只留 needs，
改完单测炸了 9 个用例——大多数边只声明 produces（无配对 needs），这条链路
正是 T-mt25ecbd 产出闸门依赖的数据源，按 role 过滤会静默削弱那次修复。
已撤回（work-graph-db.js 这次只加注释，没有逻辑改动），细节记在 33 号文档。

新增回归用例 graph-files-index.test.js ⑪：produces required:false 且该 kind
从未被索引到时不拦下游成功，同边 needs:artifact(required:true) 依旧受保护。
全量单测 998/998 通过。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

用真实 LLM 起了一条新任务（G-mt2r62ia-73af/T-mt2r6fz0-125b）回归验证 83afecb 的修
复：org-planner-sdd 自判失败后沿新补的兜底边自动回退 3 次、零人工介入，最终收敛到
completed，补上 31 号文档 §六此前用确定性测试代替的那步真实验收证据。

顺带在 org-coder 子图撞见一个独立的新 bug：inboundContracts()/requiredInputsMissing()
不按 role 过滤 graph_edge_contracts，把同一条边上声明的 produces（源节点自己产出什么）
也当成目标节点的必需输入，导致 org-coder-validator 被 missing_required_input 反复假阳
性 blocked（agent 自己判定 passed，引擎却强改成 fail）。已定位根因、写清复现证据与建议
修法，记在 33-needs-gate-role-filter-bug.md，留给下次实施。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

状态行从"评估完成，未实施"改成"方案 B 已实施"。§四风险/未决问题里原来的
4 条逐条补上实施时的实际决策：
- SessionPool 并发复用的真实后果仍未实测，但改用了不需要知道答案的设计
  （拿锁成功才调用，从设计上不会触发这个场景）
- 互斥锁选型定为抽共享模块（agent-session-lock.js），不新起一把
- 失败标记定为本体目录下的哨兵文件，不碰 system_agents.status
- 第 4 条（三处同构缺口）原样保留未决

新增第 5 条：实施时发现的连带效果——hire 路由第 1 步改 await 之后，第 3 步的
setTimeout(5000) 变成多余延迟，刻意没有顺手删掉，记录下来给以后处理。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

用户追问「这个方案能解决什么问题」，发现文档原来把这个信息拆在§三要点和§四
风险里，没有对照着讲清楚。补一张表：撞车丢请求/卡死不可见两条真解决了，
agent-creator 真的坏了/主动通知人/另外两处同构缺口/hire 接口异步体验这几条
明确没解决——避免看完方案高估它的覆盖范围。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

承接 30-task-delegation-reliability-gaps §2.1（现状调研，未拍板）。评估了两条候选：

方案 A（改走 POST /api/agent/task/dispatch）不成立：深挖发现它最终也是走
selfChat() 回环 HTTP 自己，撞上 agent-creator 单会话锁时同样吃 429、同样不
检查响应状态码——跟现在的 fire-and-forget fetch 是同一条失败路径，没有多任何
重试保护，唯一价值是任务表里多一条可查询的行（可观测性不是可靠性），且语义
错位（内部装配动作会被包装成用户可见的派单任务）。

方案 B（company.js 直接同进程调 AgentManager.callAgent）方向对，但评估中发现
一个原始方向没提到的真实风险：SessionPool.getOrCreate() 只判断连接在不在，
不判断上一次调用有没有跑完——绕开 HTTP 直接并发调用会被复用到同一个还在处理
中的会话上，两条 prompt 塞进一条 stdio 管道，行为未定义，比现在"第二个请求被
429 丢弃"更危险。因此推荐方案明确写成「同进程调用 + 自己的互斥锁 + 有限重试 +
失败落地为可查询状态」，不是简单的「同进程调用 + 重试」。

文档状态：评估完成，未实施。互斥锁选型、失败标记落点等留给实施阶段决定。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

## 起因

e2e-demo 真实任务卡住：org-planner-sdd 自己判 input_underspecified
并点名 org-planner-prd，但这张图里 sdd 没有任何 fail 出边——精确匹配、
兜底边两条路都接不住，节点直接 blocked，靠人工点了「重试」才续上。

## 根因

fail-fallback-edge 校验（27-P3/P4 §三.7 第五项）只在节点已经画了别的
fail 边时才检查兜底边齐不齐。一条 fail 边都没有的节点完全不受约束——
workgraph-planning/agent.md 原文明说这是「合法设计」。但系统里所有本体
共用 _base 的四段式协议，VERIFY 阶段任何 agent_call 节点都可能自判
失败，不止专职判词节点。四个骨架模板审计后发现 6 个中间节点存在同一个
漏洞（sdd 只是撞上的那一个）。

## 决策

除图的唯一入口节点外，每个节点必须留一条兜底边（判据是 forward 入度，
不是节点名字模式）。org 层暂不动——node 全是 subgraph 类型，失败来源
机制不同，且套用同一条规则会让三个 org 模板立刻不合法，属于 27-p3b
「验收9」还没收口的链路，留给那边一起做。

中途发现无条件收紧会炸 46 个用例/13 个文件（createWorkGraph 被大量
测试当成建最小图的通用工具）。改法是加 strict 开关，默认关闭（行为
不变），只在 workgraph-planning 真实提交图落库的那个唯一入口
（createWorkGraphSafely）打开。

## 改动

- work-graph-db.js / graph-engine.js：新规则 + strict 开关
- planner.json / executor-fanout.json：补 6 条兜底边
- workgraph-planning/agent.md：约束三等四处措辞同步
- 新增单测：strict 模式 7 例 + 真实链路回归用例（真实引擎代码+真实
  DB+只换最外层 CLI 子进程，复现 sdd 自判失败后引擎自动路由到 prd，
  全程零 retryNode 调用）——比重跑一次真实任务更严格，可回归、进 CI

978/978 单测通过。需求与决策记录见
docs/todo/system-design/31-work-graph-fail-fallback-coverage.md。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

任务表 T10 标完成；三个阶段表（A/B/C）现在全绿；顶部版本行、开篇摘要、
T11（没有单独立项，测试随各任务同批写掉）一并更新，别再让文档滞后于代码。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

T5 任务表行标完成，补一段实现记录（桩子设计、block_reason 列、
resumeBillingClearedRuns、advanceBatch 的第二个排序 bug）。

顺带记一笔过程：写 T5 期间发现 work-graph-db.js 被另一个会话同时编辑
（重写 validateFailFallback），用 git diff 生成的 patch 只保留自己的 hunk
（git apply --recount --cached）避免带上对方未完成的改动，再用一次性
worktree 单独验证后才提交。留着这条经验：共享工作目录下 commit 前先
git diff 走查一遍要提交的文件，别假设自己改的文件里只有自己的改动。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

自动模式的驱动原语 advanceTree 里 advanceOne 换成 advanceBatch：树上「最深
active run」的选取逻辑不变，但推进这一步现在能一次并发 claim 一批 ready 节点，
而不是每 tick 只推一个。核实过 advanceTree/runAuto 的返回值全仓库只被读 .ok，
不依赖 .node/.results 的具体形状，不需要兼容层。

顺带抓到并修了一个真 bug：advanceBatch 的 no-ready-node / taken-by-other 分支
原来写的是 ok:true，跟 advanceOne 用 result() helper 的惯例（这两种情形一律
ok:false）不一致。不修的话接进 runAuto 后，一个已经收敛的 run 会被自动循环
一路空转到 maxSteps 才停——旧测试从没对已收敛的 run 连续调 advanceBatch，
所以这条一直没被撞出来。

新增两条测试：ok:false 语义与 advanceOne 对齐（直接绕开引擎构造边界状态）；
runAuto/advanceTree 端到端确实吃到并行（用真实 setTimeout 延迟证明并发窗口
重叠，不是同步假象）。全量 vitest 147 文件 / 1350 用例，零回归。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

planner 骨架（brd→prd→sdd→goal-benchmark→validator）复现：三个 planning 节点
声明了 produces 却没真落盘，executor 没抛异常就被引擎判 success；goal-benchmark
的入边 needs:[brd,prd,sdd] 只用来拼提示词里的 ⚠️ 提示，agent 视而不见照样产出
合法 acceptance。下游 validator 永远读不到三份文档，backward 重试撞循环硬顶后
只能人工兜底。

settleNode 判 success 之前新增两道闸门（均只对 agent_call 节点生效，subgraph/org
节点的契约由子 work run 自己的节点过闸）：
- unsatisfiedRequiredProduces：声明的 required produces 一个候选文件都没落盘 →
  fail_reason=produces_missing，不再放行
- requiredInputsMissing：声明的 required needs 在 graph_files 里查不到实例 →
  fail_reason=missing_required_input，不采信 agent 自报的 success

两者都只判「有没有」，不判「分类对不对」——ambiguous 归类留给下游 ⚠️ 提示词处理，
避免把「写了东西但引擎猜不出对应哪个 kind」误判成没执行。

包含此前已完成但未提交的 27-P4 T3（graph_runs.max_concurrency 落库）及配套
advance-batch 测试。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

只做了这一件事，没有跟着做「dream 改成 org/work graph 来跑」——两者被
单独评估过：org/work graph 是单公司作用域（org graph=公司级 workflow，
work graph=公司内某任务的节点图），dream 却是跨公司扫描，套进去要么破坏
作用域假设要么得新开图类型；且 graph 引擎自带的验收机制（goal-contract
benchmark/test-script）判的是「产物过没过验收脚本」，对「经验提炼得对
不对」这种自由文本判断没有对应机制——不管套不套 graph 都得单独设计
rubric，是同一件事。用户明确只要 REST/控制台这一半。

## REST（server/routes/dream.js，挂 /api/dream）

路由本身没有新业务逻辑，全部委托给已测过的 dream-service.js：
GET /agents（总览）、GET /agents/:id（详情，含定义文件可写性 + 经验
审计）、POST /agents/:id/run（手动跑一次，dryRun 只看有没有新原料不
起 LLM）、POST /sweep + GET /sweep/status（全量扫描后台跑 + 轮询，内存
态并发锁防止连点两下）。

## 控制台（web/src/views/DreamConsole.vue，路由 /dream）

一个表格 + 两个弹窗：本体列表（详情/跑一次/dry-run）+ 全量扫描按钮
（15 秒轮询状态）。导航栏加 🌙 Dream 入口。

## 验证

server/tests/unit/dream-routes.test.js 4 例，monkeypatch 掉
dream-service 导出对象上的六个函数（不走真文件系统，不误扫真仓库
76 个本体），只验路由层自己的逻辑：端点接线、sweep 并发锁状态机。

真起服务器打了真数据：GET /agents/innovator-evolver 正确报
SKILL.md 因没进 git 历史而不可写、经验审计吐出上次真跑沉淀的 4 条
经验及原文；dry-run 正确报 no-new-material，没多花一次 LLM 调用。
浏览器里走了一遍列表→详情→dry-run，与直接打 API 结果一致。

955 个单测全绿。

文档：29-dream-design.md §5.7 记录实现与「为什么不做 graph 化」的
理由；28-followups.md / docs/README.md 同步更新 dream 现状。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

按任务表逐条 grep 代码，发现这份文档落后于实现相当多：

· **T1 已完成**（P3C §15.5-2）：SessionPool.maxSessions + scope key，两条守卫盯着。
· **T3 后半已完成**（P3C 批 4）：单 active root run 的唯一索引已 DROP，
  换成四步事务内准入（BEGIN IMMEDIATE → 重读 → 计数 → 条件更新），8 进程实测零超发。
· **阶段 C 整个已完成，但形态换了**：产物索引做成了 graph_files **表**而不是 files.json。
  表比文件多拿到两样：部分唯一索引保证「同一路径只有一个当前版本」，
  superseded_by 让历史版本可共存。守卫 graph-files-index.test.js 七条。
· 产物也早就按 run/node 分目录了（runs/{rootRunId}/nodes/{nodeRunId}/），
  §3.6 里「按 agent 分目录、同一 agent 不同任务混在一起」那条已不成立。

§3.6 那两个 ❌ 改成校准块 —— 保留原文（它记录了当时的判断依据），
但当前状态以校准块为准。

**真正剩下的只有阶段 B**：max_concurrency 列、advanceBatch、三层额度取小、
并行执行与部分失败降级，以及 T10 的控制台可视化。

> 这是「文档落后于代码」的又一例。判断一个阶段还剩多少工作量时，
> **先照着任务表逐条 grep 代码**，别照文档估 —— 照文档估会把已完成的三项当成待办。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

## 决策 D：能自动查的自动查，不能自动查的把回查成本降到几秒

「这条结论对不对」机器判不了，需要理解内容 —— **不假装有自动判据**。
能自动做的只有两件，两件都做了：

① **引用真伪可以自动查**：提炼产物的 sources 必须都出自这一轮真喂进去的原料，
   编一个出处直接拒（前置闸门，连去敏判定都不用调）。
   编了出处的经验是「无法验证」最危险的形态 —— 人抽查时顺着一个不存在的指针放弃，
   然后**默认它是真的**。
② **auditDistilled()**：把每条结论与它引用的原料原文并排列出来，
   指针悬空标 null（原料被清理过 / 出处是编的）。

真跑那 4 条实测：**8 条引用全部取得回原文**，模型没编出处。
⚠️ auditDistilled 的输出**不是质量分**，别当成那个用。

## 任务态清理（28 §5.6）

四道判据全过才删：① 公司在 company_agents 名册里；② 目录名在**任务态白名单**里；
③ mtime 早于 N 天（默认 14）；④ run_* 对应的 run 已到终态。默认 dry-run。

**第 ② 条是踩出来的**：第一版写成黑名单（「不在保护名单里的都算任务态」），
dry-run 直接选中了 trend-scout-global/idearun/venv 和 youtube-crawler/idearun/data
—— 一个 Python 虚拟环境、一个数据目录，都在**真公司**底下，都不是任务态。
**删错不可逆，留着最多占磁盘 —— 判据必须是「认得出才删」，不是「不认识就删」。**

读不到名册时一家公司都不认（fail-closed），守卫里单独钉了这条。
公司态（memory/ conversations/）永远走「不许清」那条分支 —— 那是 dream 的唯一原料，
删掉不可再生（28 §5.6b）。

实跑 30 天窗口：待删 0，跳过 955（556 还新 / 74 不在名册 / 60 公司态 / 11 白名单外）。

全量：145 文件 / 1338 测试全绿。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>