宜博 / lemonboss

界面走查（真 server + HTTP + 真 AgentManager，底层 mock 协议）已把
manual 模式全流程点通：org 节点起子图 → 下钻 work graph → 单步 →
第 3 步触发回退（徽标 0/3→1/3、run 级 1/5 双层计数同时可见）→
归因记录与 remediation_note 完整送达 → 收敛后父节点结算、左栏前移。

mock 侧补两处缺失接线（都是「四环漏一环」，非新功能）
- ClaudeCliProtocol._sendMockPrompt 按 agent 类型查 fixture：图执行侧的
  agent 名带公司前缀（resolveAgentName 返回 {cid}:{id}），fixture 不该
  按公司复制一份。DevLoop 侧名字不含冒号，行为不变
- graph-engine.defaultAgentExecutor 接住 mock/files 事件：此前只有
  DevLoop 的 loop-controller 接，图执行侧没接，于是 mock 下
  readNodeProduct 永远找不到 attempt-{n}.json，validator 系节点恒 blocked。
  写入限制在节点产物目录内，越界丢弃并留痕

新增 5 份 P3 fixture（workgraph-planning / prd-planning / sdd-planning /
coder-validator / validator-triager），coder-validator 用 sequence 演示
一次回退。图必须放 chunks 不能只放 result——callAgent 的 output 来自
流式 chunks，session/result 的文本不进 output。

控制台入口：CompanyDashboard 加「🕸️ 执行控制台」按钮（路由早已注册，
此前无任何入口，只能手敲 URL）。

scripts/p3-demo-setup.js：手工测试准备脚本（雇人+写图+起 run），头部
写明它是两个已知缺口的绕行，缺口修好后第 1 步即可删。

_registry.json 补齐 6 条本体登记（brd/prd/sdd-planning、goal-benchmark、
benchmark/testdata-validator）——同轮新增的 template-refs 防线测试正是
因为缺这 6 条而变红，防线抓到了「交付与报告不符」。

文档
- 27-REQ R-18：招聘归 workgraph-planning（方案 a）、停用 mock 改真 CLI
- 27-P3B 真实运行前置（新增）：11 个工作项分三批，含现状核实 10 条证据
  （seedTemplates 无运行时调用方、10 条悬空 company_hired 行、
   FAILING_VERDICTS 不含 "fail" 导致验收假放行等）

测试 719/719 全绿（66 文件）。

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

按 docs/README.md 既有约定（done/ 放「已实现/当前有效」），把两份已落地的
阶段设计文档移入 done/system-design/：

- 27-p1-virtual-reference.md  P1 虚拟引用寻址，commit 226489d
- 27-p2-org-graph.md          P2 Org Graph，70a4727 + f20d0d8，真实建公司端到端验证过

用 git mv 保留历史（R098 / R087）。移动断掉的 33 处相对链接已全部修复：
moved 文件内的出向链接改 ../../todo/system-design/，todo/ 下 6 个文件的入向链接
改 ../../done/system-design/。全 docs/ 扫描无断链。

README 此前严重过时——只列了 2 份 27 文档，实际已有 11 份。本次补全 todo/ 表格，
每份标注状态与作用（总纲 / 需求源头 / 命名规范 / 端到端 / 参考场景 /
P3+P4 已实现 / 验收契约 / P4 设计中），并在 done/ 表格补上 P1、P2 两行。

■ 刻意没有移动 27-p3-p4-work-graph-console.md
它虽然已实现（c3abf4a），但文档正被另一进程持续修改（工作区 M 状态）。
移动会打断它的编辑路径，等它收尾后再归档。

■ 三份文件的链接修复留在工作区未提交
27-naming-conventions.md / 27-p3-p4-work-graph-console.md / 27-requirement.md
里，我的链接修复与另一进程的在途编辑混在同一文件中，单独拆分风险大于收益。
工作区内容是正确的（链接已指向新路径），会随它下次提交一并带上。

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

■ 关于编号
原「P4 回退 + Loop-Validator」已并入 P3 实现完毕（c3abf4a：双层熔断、五项结构
校验含 fail-fallback-edge、三层暂停级联、contract_hash 重试判据）。本文档回收
这个空出来的编号，装 P3 明确排除、现在成为最大能力缺口的内容。

■ 核心：fan-out 并行
P3 把图结构和 join 语义都做好了，唯独没做并行本身：
- graph-engine.js:1078 出边评估「所有入边满足才置 ready」——fan-in join 正确
- graph-engine.js:908  拾取 SQL 是 LIMIT 1——三个并行分支只会一个个串行跑掉

设计为 advanceBatch(runId, {maxConcurrency})，不新增第二个推进原语：
手动模式 maxConcurrency=1 时行为与今天的 advanceOne 完全一致，P3 已有调用方
和测试不用改；自动模式一次拾取整批。批量拾取必须在一个事务里一次性置 running，
否则两个并发 advanceBatch 会拾取到重叠集合。

■ 走查发现的关键事实：隔离挂载点已经存在
session-pool.js:29 的 getKey(agentName, agentConfig, workDir, scope) 签名里
早就预留了 scope 参数，但第 45 行实际调用时没传。所以「同一 agent 多实例隔离」
这个并行前置条件的改动量比预想小得多——用 graph_run_nodes.id 作 scope 即可。

连带要放宽 CONVENTIONS §12 第一条不变量：(pid, agent) → (pid, agent, scope)。
这是 P4 里唯一要动 DevLoop 规格的地方，且 _spec/ 是生成物，必须改 HTML 后跑
npm run spec:extract。该放宽同时是 P6 的前置——DevLoop runProject 波内串行
（loop-controller.js:609 注释「串行跑」）正是被同一条不变量挡住的。

■ 产物统一目录 + files.json
这是此前提出但一直未实现的需求。按 task 分目录
data/companies/{cid}/tasks/{taskId}/，根目录 files.json 作统一检索索引，
由引擎在产物落盘后自动追加（不靠 agent 自觉写，否则索引必然漂移），
并支持从 graph_run_nodes 行 rebuild。与 output_ref 不重复：后者是节点级指针，
前者是公司级聚合视图，由前者派生。

■ 三个阶段，C 完全独立
A 隔离(T1-T2) → B 并行(T3-T6,T10)；C 产物索引(T7-T9) 与 A/B 无依赖，可最先做。

并发上限对齐 plan-cost-concurrency.md §④ 的既有数字（run≤5 / 公司≤3 /
单机≤20 session），不另立一套。

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

命名轴是「节点在哪一层图里」，把散落的老 agent 归到它实际所处的层级：

  innovator → org-innovator      type='cxo'，是 org graph 层的节点
  hunter    → innovator-hunt     innovator work graph 第 1 阶段
  digester  → innovator-digest   第 2 阶段（输入是 hunt 产出）
  evolver   → innovator-evolver  第 3 阶段

依据：retrain-pipeline.js 的 stepConfigs 就是按 hunter → digester → evolver 顺序
跑的，行 231 明写 steps: ['re_hunt','re_digest','evolve'] —— 这三个本来就是
innovator 的 work graph 三阶段，只是名字没体现出来。

■ 迁移（scripts/migrate-agent-naming.js，--dry-run + 幂等可重跑）
- 8 个目录（system/agents/ + system/templates/），用 git mv 保留历史
- system_agents 表 4 行的 id 与 legacy_path
- 公司实例目录与 company.json.agents[]（本次无公司雇过这四个，实际 0 条）

■ 代码引用点（5 处，手工改）
- retrain-pipeline.js: stepConfigs 的 agent 字段 ×3、agentToStep 映射的 key ×3、
  call_sub_agent 的 evolver 判断
- agent-chat.js: agent 列表过滤里的 innovator
- company.js: 模板训练触发的 agentId

■ 刻意不动的三类同形异义（改了会坏）
1. skill 内部子目录名 {skillDir}/hunter/knowhow.md —— 那是 hunt/digest/evolve
   三阶段的产物目录约定，与 agent 名同形但不同义。涉及 open-api.js:402、
   retrain-pipeline.js:148/374、evolution-loop.js:178、sync-skills.js 的 INTERNAL_DIRS
2. skill 命名空间白名单 —— skill-dir-manager.js 的 CORE_SKILLS、
   migrate-trained-skills.js 的 SYSTEM_SKILLS，那里的 'innovator' 指同名 skill
3. conversations/ 与 system/tasklog/ 下的历史记录 —— 运行态数据，不改写历史

evolver-youtube-crawler 按 §3.4 列为待定，迁移脚本按精确目录名匹配，未误伤。

这四个重命名顺带解决了 27 号文档 §七 挂了很久的 6 个命名冲突 id —— 重命名后
system/agents/ 与 system/templates/ 下不再有同名目录（只剩 agent-creator 与
evolver-youtube-crawler 两个，前者是基础设施角色按规则不改名）。

验证：npm run test:unit 693 全绿（64 files）；test-company-e2e 114/114；
迁移脚本二次执行 dirs=0 dbRows=0 skipped=8（幂等）。

未触碰另一进程正在进行的 P3 文件（graph-engine.js / graph-run-sse.js /
work-graph-db.js / 27-p3-p4-work-graph-console.md / 27-requirement.md）。

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

按 27-p3-p4-work-graph-console.md v0.3 实现，三轮开发+校验后测试全绿
（693/693，P2 26/26、DevLoop 230/230 未被打破，web:build 干净）。

服务层
- work-graph-db.js  定义层(work_graph_*) + 运行时层(graph_runs/graph_run_nodes/
  graph_run_loop_records) 五张表；状态转换表照 unit-registry 模式；
  复用 org-graph-service 四项校验 + 新增第五项 fail-fallback-edge
- graph-engine.js   advanceOne 幂等原语；agent_call / subgraph 两种 executor；
  手动与自动共用同一原语；双层熔断（单边 loop_count + 按 root_run_id 共池的
  backward_count）；任务级预算挂 root run；三层暂停/停止级联；
  重试按 contract_hash unchanged 判据
- graph-run-sse.js  按 run_id 广播，状态转换+timeline+SSE 三者原子化
- goal-contract.js  验收契约格式与执行器（R-15.6 验收先行）

引擎泛化（R-15.4）：org graph 与 work graph 走同一套 advanceOne，
定义层两套、运行时层一套，三层下钻用 parent_run_id 链。

R-16 失败归因：validator-reflection 专职归因节点；fail_reason 多边路由
（精确匹配→兜底边→死路）；子 run 收敛透传 success/fail + fail_reason +
remediation_note 三值；infra_flake 不烧任何计数。

路由 / 前端 / 模板
- routes/graph-run.js 八个端点；company.js 任务入口
- WorkGraphCanvas.vue 扩展 UnitsDAG（subgraph 角标、backward 虚线曲线、
  N/3 循环徽标、异常流程视觉降权）；GraphConsole.vue 三栏 + 四 tab 详情
- 五个新 agent 模板：validator-reflection / org-validator / planner-validator /
  coder-validator / workgraph-planning

命名统一（R-15.3 + NAMING §三）：org 节点改为 org-{职能}，
三个 org-graph 模板末节点收敛到 org-validator；org_graph_edges 加 fail_reason
列并把唯一索引补上该列（避免精确边与兜底边互相吞掉）。

三轮校验修掉的主要缺陷：subgraph 重跑不起新子 run 导致永久死锁；
SSE/timeline 零调用方；org 侧 fail_reason 写入被丢弃；fail-fallback-edge
只做了一层；backward_count 跨 run 树重置架空熔断外层；
seedEntryNodes 误点亮只有 fail 入边的节点。

已知缺口见后续提交：remediation_note 仅在 backward 边落库、
total_tokens 预算维度无生产方。

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

命名轴从「业务领域」({domain}-{职能}) 改为「所在图的层级」：
  org graph 节点   org-{职能}              org-planner / org-coder / org-validator
  work graph 节点  {父 org 节点全名}-{职能}  org-coder-validator

三个模板因此首尾同名，只有中段职能不同——规划和验收本身不分领域：
  dev      org-planner → org-coder   → org-validator
  content  org-planner → org-writer  → org-validator
  ops      org-planner → org-monitor → org-validator

■ NAMING §三 补上此前完全缺失的一条轴：节点名 ≠ 本体名
R-15.3 指出的关键区分。禁止裸用 validator 的理由是「一家公司内两个节点不能
重名」，该理由针对节点、不针对本体。本体若被迫带前缀，coder-validator 会复制成
org-coder-validator / content-coder-validator 多份，与 P1「同一份本体、多处引用、
各自私有语境」直接冲突。落到 schema 上就是 node_name / system_agent_id 两个字段。

同时写入 §3.3（三个 validator 是三个独立本体，验的东西本质不同，与 §八bis
「不特化」原则不冲突）与 §3.4（存量 agent 归位：innovator→org-innovator、
hunter→innovator-hunt、digester→innovator-digest、evolver→innovator-evolver，
依据是 retrain-pipeline.js 里三者就是 innovator work graph 的三阶段）。
§3.4 顺带解决 27 号文档 §七 挂了很久的 6 个命名冲突 id。

■ 代码层已改
system/org-graph-templates/{dev,content,ops}.json + README、
system/templates/orggraph-planning/{agent.md,tools.md}

■ 代码层未改（已在 §3.4 末尾标注）
§3.4 的四个存量 agent 重命名需要单独一次迁移（目录改名 + system_agents 表 +
retrain-pipeline.js 等引用点），本次未做。

验证：三张模板图改名后实跑 validateGraph 仍全部通过四项校验；
npm run test:unit 676 全绿；test-company-e2e 114/114。

未触碰 27-p3-p4-work-graph-console.md（另一进程正在做 P3 开发，且其中命名已符合
R-15.3）与 27-requirement.md（原文照搬文档）。

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

R-16（归因由专职 subagent 做，回退边多条）：
- §四.D.2.2 归因改为 org-validator work graph 内的 validator-reflection
  专职节点，与 DevLoop 的 Integrator/BugTriager 分工同构；给出四类
  fail_reason 取值与 DevLoop 四分类的对照
- §四.D.0 子 run 收敛改为透传三值（success/fail + fail_reason +
  remediation_note），归因结论才能穿透子 run 边界供父层选边
- §四.D.2.1 熔断改为双层计数：单边 loop_count 防同路径死循环，新增
  run 级 backward_count 防"换个借口继续退"——多条回退边各自计数会把
  硬顶架空成 3xN；infra_flake 不烧任何计数
- §三.7 写入前校验新增第五项 fail-fallback-edge（强制兜底边）
- schema：graph_runs 加 backward_count
- 任务表加 T13/T14，验收标准加 9b/9c/9d
- skill_defect 属 L4，v1 保留归因取值但动作降级为挂起等人工

base agent 四段式（新增 §九bis）：
- 核实后原表述"已强制一套四段式生命周期"只对一半
- Context Flush / P0 事前阻断阀 / OKR 联动确实在跑
- Hot Swap 换技能包静默失效：system/skills/ 目录不存在，
  agent-chat.js:1908 的 existsSync 守卫使其空转且不报错
- 后果：EXECUTE 才拿破坏性权限只剩 prompt 话术约束，无机制保障
- phase 参数无取值/顺序校验，且被直接拼进文件路径

需求文档：补回 R-15.1 全文、R-15.4 后半、R-15.5、R-15.6 及速查表
对应行（此前被误回滚丢失），新增 R-16 条目。R-15.3 的命名表保留
NAMING §三 重写后的版本，未还原旧版。

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

■ 前端路由遮蔽（既有 bug，被 P2 的 T8 暴露）
web/src/router/index.js: CompanyAgentChat 的 path 是 /:id/agents/:agentId? ——
agentId 可选，导致它抢占 /:id/agents，而导航栏「Team」正是指向这个地址。
结果 CompanyDashboard 的团队 tab（连同 P2 新增的 Org Graph 区块）完全不可达，
点 Team 打开的一直是 AgentChat。改为 :agentId 必填。

■ Org Graph 空边时凭空画出流程链（P2 T8 的 bug）
0 条 forward 边时所有节点入度都是 0，全部落进拓扑序且 degraded=false，
模板照常在节点间渲染 → 箭头，凭空捏造出一条并不存在的流转顺序。
P0 迁移进来的存量公司（有节点无边）全部中招。新增 orgGraphNoEdges 判定：
这种情况只平铺、不画箭头，并明确提示「尚未定义流转顺序」。

■ create() 仍在建 goals/ 目录（我在 OKR 正名 74ea1ff 里的遗漏）
company-service.js 的 subdirs 列表没跟着 goals→okr 一起改，新建公司仍然产出
goals/ 空目录。改为 okr/。

■ test-company-e2e.js 从「第 4 个断言就崩」修到 114/114 全绿
该脚本长期整体失效，HEAD 版本同样全断言失败。四类问题：
1. 路径过期：data/{id}/ → data/companies/{id}/；data/templates/ →
   system/templates/；data/agents/master → system/agents/master
2. Phase 4 用 ceo 模板测「骨架是否完整复制」——但 system/templates/ceo/ 只有
   plan.md + todo.md，没有 agent.md/soul.md/config.json，测不出东西，且缺
   config.json 就没有 type='cxo'，company.ceo 也标不上。改用同为 cxo 且文件
   完整的 coo。（ceo 模板本身的残缺是另一个待补的问题）
3. 断言停留在 P1 之前：P1 虚拟引用（226489d）之后 agent.md 不再物理拷贝，
   改为 config.json.systemAgentRef + company-context.md。按新模型改写
4. 断言停留在 T5b 之前：模板不存在时返回 hired_from_base 而非 training

顺带记录一个设计缺口（未改，仅在测试注释里说明）：system/templates/base/
目前只有 agent.md + config.json，所以 base 继承出的骨架不含 soul.md /
identity.md / tools.md / todo.md，也不含 AgentScaffold 的标准子目录结构
（memory/short-term、knowledge、workspace 等）。这些依赖 agent-creator 填充。

另删除 OKR 迁移的 *.bak-goals 备份目录及其 .gitignore 规则。

验证：npm run test:unit 676 全绿；test-company-e2e 114/114；web:build 通过；
Chrome 实机确认 Team tab 可达、空边提示正确。

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

- §八.1 单一入口：R-13.4 已定案，标记关闭，保留放宽条件的论证供将来参考
- §八.3 建公司耗时：实测约 30 秒（非几十秒到几分钟的估计）；补充说明前端
  空态未真正区分「规划中」与「确实无图」，是刻意简化
- §八.5 前端画布：已按占位形态交付，不阻塞 P2

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

真实建公司验证时发现的两个串联问题——只有起真服务才暴露得出来，
工作流的集成 agent 全程没起过服务，测试也覆盖不到。

1. 地址错误：orggraph-planning 是被 hire 进公司的，住在
   data/companies/{id}/agents/ 下，寻址必须是 `{companyId}:orggraph-planning`。
   原代码请求裸名 /api/agent/orggraph-planning/chat → 404 Agent not found，
   agent 从未被触发，公司永远停在空壳状态。

2. 失败被静默吞掉：fetch 只在网络层出错时 reject，4xx/5xx 不会 reject，
   所以原来的 .catch() 从头到尾没打印过任何东西。补 res.ok 检查 + 成功日志，
   这类"地址写错"的问题以后能第一时间看见。

修复后端到端验证通过（临时公司 p2-verify，验证完已清理）：
- POST /create → company.goal 落盘、orggraph-planning 被招聘且因 meta-bootstrap
  被正确排除在 org graph 外
- 日志出现 "✅ 已触发 p2-verify:orggraph-planning" + ACP 会话创建
- 30 秒内 agent 产出 4 节点 5 边的图并完成 4 个角色招聘
- agent 选中 dev.json 且**扩充**出模板没有的 code-tester（goal 要求带单测），
  并在规划记录里明确排除了 content.json 的歧义（"Markdown/HTML 是被处理的
  数据格式，不是要产出的内容作品"）——模板作为"起点集合"的设计意图成立
- 产出的图实跑 validateGraph 通过四项校验
- 四个角色 config.json 均为 inheritedFrom=base（元 agent 继承路径生效），
  system_agents 里 scope='company' + owner_company_id 正确
- orggraph-planning 收尾后 heartbeat.enabled=false，正确休眠

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

用 9 个并行 agent 按「文件独占」划分实现 P2 的 T1-T9（T0 已于 2255f09 完成）。
详见 docs/todo/system-design/27-p2-org-graph.md §五。

阶段 A · 数据层
- graph-db.js: org_graph_nodes 加 status/reports_to_node_id（PRAGMA 探测后 ALTER，
  幂等）；全量唯一索引换成 WHERE status='active' 的部分索引，使「fire 后重新 hire
  同角色」可行；org_graph_edges 重建为执行流边（condition/edge_kind/status）
- graph-service.js: ensureOrgGraphNodeIndex 同步改建部分索引，且 upsertOrgGraphNode
  的 ON CONFLICT 必须写成 ON CONFLICT(company_id, role_name) WHERE status='active'
  —— SQLite 的冲突目标要与部分索引谓词逐字对应，否则整条 INSERT 直接失效
- org-graph-service.js（新）: validateGraph 四项校验 + writeGraph/patchGraph/
  getGraph/removeNode，事务化，节点软删除级联失效相关边
- routes/company.js: 四个端点 POST/PATCH/GET /org-graph + POST /org-graph/replan；
  /create 接入自动招聘 orggraph-planning + 异步触发（失败降级为空壳公司）；
  /fire 接入节点软删除

阶段 B · 自动生成
- system/org-graph-templates/{dev,content,ops}.json + README：三张三段式骨架
  （规划→执行→验收，验收失败回退到执行节点），角色名遵循 {domain}-{职能}
- system/templates/orggraph-planning/：新 system agent（type='meta-bootstrap'），
  含 §4.1 八步工作流
- company-service.js: 模板不存在时从 system/templates/base/ 元 agent 继承骨架
  （自动带 RESEARCH→PLAN→EXECUTE→VERIFY 四段式）+ agent-creator 填充，
  新建 agent scope='company'。这是 27-E2E §八bis 元 agent 继承的落地点

阶段 C · 展示
- CompanyDashboard.vue: 组织流程拓扑链渲染 + 空态降级 + 环深度保护

并行编排中发现并修复的三处（均不在原任务划分内）：
- AppNav.vue 建公司表单缺 goal 输入框 —— T0 只改了后端，前端表单没同步，
  company-goal 实际传不进来。这是上一轮 T0 的遗漏
- graph-seed-service.js 会把 type='meta-bootstrap' 的 orggraph-planning 塞回
  org graph，与 hire() 的 guard 不一致
- graph-agent-p1-acceptance.test.js: hire 未知角色的返回从 needs_training 改为
  hired_from_base（T5b 的行为变更），断言同步

验证（独立复核，非 agent 自述）：
- npm run test:unit 676 passed / 63 files（基线 652，+24 为新增的 org-graph 用例）
- npm run web:build 通过
- 三个模板 JSON 实跑 validateGraph 全部通过；四类非法图各自被对应 rule 拒绝；
  writeGraph→getGraph→removeNode 级联验证通过（删中间节点后 3 条边全部失效）

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

11 个任务（T0-T9 含 T5b）此前只有一句话的顺序说明，没有阶段概念。按依赖收敛为：
- A 数据层（T1→T2→T3、T7、T9）：纯后端不起 LLM，可手工建图/校验/读
- B 自动生成（T4→T5→T5b→T6）：引入 orggraph-planning，建公司自动出图
- C 展示（T8）：Dashboard 渲染，还依赖 P3 画布组件

每阶段给出可验收标准，且阶段间可停——A→B 即可看到端到端效果，C 可后延。
T0（company-goal）已于 2255f09 实现，是 B 的前置，不计入阶段。

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

company-goal / task-goal 按作用域命名，subagent-goal 按执行者命名，轴不一致。
统一为 subtask-goal。

27-REQ R-13.1 的原话引用保留提出时的用词「subagent-goal」不改写——原文照搬
文档不参与批量替换（这是上一轮误改 R-10 原话引用留下的规矩）。新增 R-14 记录
本次定名及其与 R-13.1 的关系。

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

起因：逐条比对 27-REQ 的原话与 P2 v0.4，发现四处偏离，其中两处是设计悄悄
改变了原意。本次修正并落定。

代码（P2 §五 T0）：
- company.json 新增 goal 字段（company-goal），create({id,name,goal,description})
- POST /api/company/create 与 update() 同步支持
- 修的是一个实打实的遗漏：R-6 原话是"写入 company 的目标和描述"（两个字段），
  而 create() 一直只有 description。orggraph-planning 规划流水线的主依据本该是
  company-goal，此前根本拿不到。

文档定案（R-13）：
- R-13.1 goal 三层递归：company-goal / task-goal / subagent-goal，与"验收逐层
  递归"对应。澄清 R-12 说的"唯一的那个 goal"其实是 task-goal；三个验收 agent
  保持通用不按层级拆分。记录一处待定：subagent-goal 按执行者命名，与另两个的
  作用域命名轴不一致（按轴应为 subtask-goal）。
- R-13.2 公司类型完全由 orggraph-planning 推断 —— 这条**推翻了我自己记的一个
  缺陷**：审计时我把"不加 type 枚举字段"记为擅自偏离原话，实际那正是所需，
  当前设计无需改动。
- R-13.3 新 agent 从 system/templates/base 元 agent 继承骨架（自动带四段式
  RESEARCH→PLAN→EXECUTE→VERIFY）+ agent-creator 填充，而非直接走 needs_training
  全量培养；新建一律 scope='company'；innovator 训练是可选后置步骤。
  这是 R-9.2"所有 node agent 由元 agent 继承生成"在 P2 的落地点（新增 T5b）。
- R-13.4 org graph 强制单入口，原 open question 关闭。

顺带修掉 P2 的一处内部不一致：§六 承诺"提供手动触发 orggraph-planning 的端点"
给存量公司补图，但 §四.3 API 表和 §五 任务表都没有。已补 POST …/org-graph/replan。

另更正 R-11 中"代码层未执行"的过期表述——OKR 正名已于 74ea1ff 实施完毕。

回归：npm run test:unit 652 例全绿。

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

代码层：
- server/services/goals.js → okr-service.js；GoalsService → OkrService
  · this.goalsDir → okrDir，目录 goals/ → okr/
  · ID 前缀 G- → O-；落盘文件 goal.json → objective.json
  · updateGoal → updateObjective，_nextGoalId/_saveGoal 等同步改名
  · parseNodeId 层级名 ['Goal','Objective','KeyResult','SubTask']
    → ['Objective','KeyResult','SubTask','SubTask']（OKR 无 Goal 这一层）
- server/routes/goals.js → okr.js；:goalId → :objectiveId
- 7 处调用点同步：index.js / agent-server.js / agent-chat.js / company.js /
  company-heartbeat-service.js / prompt-builder.js / test-company-e2e.js
- 前端 OkrDashboard.vue / CompanyDashboard.vue 切到 /api/okr（前后端命名终于一致）
- bin/lemon.js 新增 okr create/add-node/list/status

向后兼容（不破坏任何现有调用方）：
- /api/goals/* 与 /api/company/:cid/goals/* 全部保留为别名，与新路径同时挂载
- task dispatch/report 同时接受 objectiveId(新) 与 goalId(旧)，写入时两字段都留
- bin/lemon.js 保留 goal * 命令别名

迁移脚本 scripts/migrate-goals-to-okr.js（npm run okr:migrate）：
- 目录 data/{,companies/*/}goals/ → okr/；条目 G-xxx → O-xxx
- 改写 objective.json 的 id / nodes 的 key / children 数组、_index.json、
  progress.json 的 goalId、history.log 文本、system/tasklog/*.json 的 goalId+nodeId
- --dry-run 预演；幂等；迁移前自动备份为 *.bak-goals（已加入 .gitignore）
- 处理一个反直觉边界：OkrService 构造函数会自动 mkdir 目标目录，"okr/ 已存在"
  不等于"已迁移过"——只要服务被 require 过一次就留下空壳。用 isEmptyOkrDir()
  区分空壳与真实数据，空壳移除后继续迁移。这个 bug 是在 fixture 上验证时发现的。
- 同样在 fixture 上发现并修掉：nodeId 的值漏改写、tasklog 迁移不幂等

验证：新增 server/tests/unit/okr-service.test.js（7 例，覆盖新命名工作正常 +
迁移纯函数的 ID 改写）；全量 npm run test:unit 652 例全绿。

范围说明：NAMING §五 的 benchmark 三分（skill-/agent-/goal-）本轮未动代码——
该节自身的建议就是存量保持现状、只对新增代码强制前缀，因为 benchmark_runs 等表
服务于线上 Arena 排行榜，改表名/路由是另一次独立迁移。
§二-四 的新 agent id 尚不存在实体，待 P2/P3 实现时按规范创建。

已知遗留（非本次引入）：server/scripts/test-company-e2e.js 早已失效——它按
data/{id}/ 找公司，而 company-service 用的是 data/companies/{id}/，在 HEAD 版本
同样全部断言失败。本次只同步了其中的 OKR 命名，未修这个路径问题。

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

改名：task-benchmark / task-test-data / task-test-script
   → goal-benchmark / goal-test-data / goal-test-script

理由（推翻此前"验收标准跟着一次 task 执行走"的论证）：关键区分是基数。
一个人类需求描述 = 1 个 goal，是验收的边界；而 goal 在图中会分解出 N 个 task
（并行分支、下钻的 sub agent）。验收回答的是"人类想要的东西做到了没有"，
这是 goal 级判定；挂在 task 上会导致"以哪个 task 的验收为准"无法回答。

NAMING §一 作用域表补入 goal / task 两行及其基数定义；§四 重写选型理由；
§六 增加与 §四 的辨析注（OKR 从 goal 解放后，goal 被重新赋予"人类需求"新义）。

连带：
- acceptance.json 的键改为 goal_id
- work_graphs schema 补 goal_id，与 okr_node_id / task_id 并列（三者基数不同，
  分别是 1 / 长周期归属 / N，不能用单一字段表达）
- 新增 27-REQ R-12 记录本次决策及其推翻关系

修复上一轮的一处失误：全局改名误改了 27-REQ 中的原话引用（R-10 一度被改成
"goal-benchmark 或者 goal-benchmark"）。原文照搬文档不得被批量替换触及，已还原。

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

此前 27 系列全部是对用户需求的转述与结构化解读，原话一句都没留存
（搜 "judge-loop-jump"、"元 agent 架构来继承生成" 等关键短语均 0 命中）。
转述会漂移，出现"当初到底怎么说的"争议时缺少可回溯的依据。

格式与定位对齐仓库既有惯例 docs/prd/newfunction/_spec/requirement.md
（DevLoop 的原始需求页："用户提出的需求原话照搬，再做结构化解析"）。

内容：11 条需求原话逐条照搬（R-1..R-11），含笔误一律保留
（validtor / syste agent / intergration / fin in / object-key result），
每条标注落在哪份文档的哪一节，附"需求 → 设计落点"速查表。

同时记录三处关键推翻关系，便于回溯设计演变：
- R-7 推翻了"benchmark/test data 是系统基础设施"的误读
- R-9.1 推翻了 P2 v0.1-v0.3 的静态汇报结构建模及 A/B/C 三个折中方案
- R-9.4 使跨公司污染风险及其三个缓解方案全部作废

另澄清 27-EXAMPLE 的「配图工厂」是为走查虚构的场景，非用户原始需求。

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

四处写 _registry.json 的地方都用 JSON.stringify(registry, null, 2) 直接落盘，
不带末尾换行。文件在仓库里是带换行的，导致任何一次 hire()/depositTemplate()/
模板增删改之后，git diff 都会多出一行 "\ No newline at end of file" 的噪音，
把真实的数据变更淹掉。

写入点：
- company-service.js:374  depositTemplate()
- company-service.js:824  _updateTemplateUsedCount()
- routes/company.js:86    PATCH /templates/:templateId
- routes/company.js:120   DELETE /templates/:templateId

同时提交一次真实的运行时数据变更：qa-judge usedCount 7 → 8。

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

新增四份文档：

- 27-e2e-task-execution-flow.md — 跨阶段总览：建公司 → 下达任务 → org graph
  逐节点执行 → work graph 规划与循环 → 验收收敛。核心发现：这套流程 70-80%
  已在 docs/prd/newfunction/_spec/ 里被完整设计（DevLoop 的 L1/L2/L3 三层循环、
  BugTriager 四分类归因、分级预算熔断、contract_hash 闸门），DevLoop 实为本
  架构唯一跑通的参考实现，通用引擎应从它抽象而来。
- 27-example-dev-company-walkthrough.md — 参考场景走查，把架构在一家具体公司
  上跑一遍数（各阶段 JSON 形态、fan-out/fan-in 图、成本估算 ~44 次调用、
  按阻塞程度排序的 8 个断点清单），作为实现靶子与端到端验收场景。
- 27-naming-conventions.md — 统一命名规范 {作用域}-{职能}。消歧三种 benchmark
  （skill- / agent- / task-）；OKR 体系正名（goal → okr，第 1 层 Goal → Objective）；
  规划类统一为 orggraph-planning / workgraph-planning / brd-prd-sdd-planning。
- 27-p3-p4-work-graph-console.md — P3/P4 合并设计：Work Graph 执行引擎（支持
  启动/下一步/暂停/停止/重试，手动与自动共用同一 advance 原语）+ 执行控制台页面。

重写 27-p2-org-graph.md 至 v0.4：Org Graph 从「静态汇报结构」重定位为
「company 级别生成的 workflow」，与 Work Graph 同构（condition/edge_kind 执行流边），
两层共用同一套 schema、执行引擎与画布组件。org_graph_edges 从未写入过数据，
可直接 DROP 重建，零迁移负担；hire() 不再需要 reportsTo（图整体规划整体写入），
P2 对 company-service.js 的侵入缩至零。

同步修正总纲至 v0.3：Org Graph/Work Graph 术语定义、§3.1 架构图、§3.3 整节；
标注 P1 已实现（226489d）；P6「DevLoop 收编」从「可选」改为「应前置」。

修正三处过期陈述：P1 已实现（非设计稿）、runProject 已完整实现（非 501）、
UnitsDAG.vue 已实现 Kahn 分波 DAG 渲染（画布应扩展而非重写）。
并记录一处待处理冲突：graph-service.js:44 已落地的全量唯一索引与 P2 需要的
部分唯一索引冲突，实现 T1 时必须先 DROP。

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

# Conflicts:
#	system/agents/master/.claude/scheduled_tasks.json

- New docs/README.md indexes the tree: done/ (shipped features + reference manuals),
  todo/ (current focus — Graph Agent architecture), todo/future/ (deprioritized
  roadmaps: FDE pipeline todo list, stale v1.1 milestones, harness engineering
  proposal — orthogonal to the Graph Agent work, not blocking it)
- Move completed/reference docs into docs/done/ (LEMONBOSS-SYSTEM-DESIGN, architecture-v5,
  claude-code-cron, open-api-manual, qa_judge_req, task_timeline_design, user-guides/,
  system-design/01-26 minus the three moved to todo/future/) — verified against actual
  code (qa-judge template, Task Timeline route/service/view) before filing as done
- Fix the two TOC links in LEMONBOSS-SYSTEM-DESIGN.md that would otherwise point at the
  old paths after the move
- docs/todo/system-design/27-graph-agent-architecture.md: add the P2 Org Graph doc link
  in the roadmap table and 关联文档 section
- Add docs/todo/system-design/27-p2-org-graph.md (P2 requirements & design, drafted in
  parallel while P0/P1 landed)

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

…_DIR move, stray files

- CLAUDE.md: document DevLoop subsystem (spec-first workflow, project root/git-vault,
  mock mode, L1 loop, unit layout, audit trail) and add missing test commands
- server/routes/agent-chat.js, server/services/task-service.js: TASK_META_DIR moved
  from system/agents/.tasks to system/tasklog
- system/agents/master/.claude/scheduled_tasks.json: scheduled task state update
- remove stray memory/daily/2026-04-02.md and a garbled-filename artifact left under
  system/agents/digester-youtube-crawler/

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

hire() now checks system_agents (source_kind='template') before provisioning a new
company agent: if the role has a shared template row, skip copying agent.md and
instead let AgentManager.getAgentConfig()/PromptBuilder.build() resolve the prompt
from the shared legacy_path at call time, with per-company context assembled from a
new company-context.md. Roles without a template row (including the 6 ids that exist
in both system/agents/ and system/templates/, e.g. evolver-youtube-crawler) fall back
to the existing full-copy behavior unchanged.

- server/services/graph-service.js (new): lookupSharedAgentMd(), upsertOrgGraphNode()
- server/services/company-service.js: hire() reference-mode branch, _provisionReferenceAgent()
- server/src/core/agent-manager.js: getAgentConfig() resolves prompt/companyContextPath
- server/src/core/prompt-builder.js: build() concatenates company-context.md
- unit + integration tests covering all 6 acceptance criteria from
  docs/todo/system-design/27-p1-virtual-reference.md §6, including a regression test
  against the real idearun:evolver-youtube-crawler naming-collision case

Full regression suite (587 tests) passes; independent adversarial review found 0
blocking/major issues.

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

Adds server/services/graph-db.js (new data/graph.sqlite: system_agents,
org_graph_nodes, org_graph_edges) and graph-seed-service.js, which scans
system/agents/, system/templates/, and data/companies/*/company.json into
seed rows without touching company-service.js's existing hire/copy path.

Real repo data diverged from the design doc's original estimates (8 not 10
global agents; 39 not 34 template dirs; system/agents/ and system/templates/
turn out to share 6 ids describing the "same" agent from two different
files) — documented in docs/todo/system-design/27-graph-agent-architecture.md
section 7 for P1/P2 to resolve.

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

First successful real-CLI agent invocation. After REAL.1 (system-prompt
injection) + REAL.2 (mtime-diff file detection) wired, the only remaining
gate was Claude auth. Once CLAUDE_CODE_OAUTH_TOKEN was added to the
project .env, scripts/real-pm-smoke.js completed cleanly:

  Wire-up status:
    ✓ process spawn
    ✓ stream chunks       (3)
    ✓ result text          (Claude returned "DONE")
    ✓ files written        (6: prd/index, feature-tree, user-flows,
                              product/overview, assets/shell.{css,js})
    ✓ git commit           (8cb0493)
  5/5 checks passed · elapsed 163s

PM output quality (real Claude, not mock):
- valid <article data-doc="prd" data-rev="1"> + <section data-rev="1">
  structure per system prompt
- nav links use correct relative paths across 4 chapters
- pid (p-7gwlbl) embedded in HTML metadata
- 中文 prose in the requested 克制 voice

Spec-deviation confirmed (no MCP tool gateway yet — Claude only has
built-in Read/Write/Bash):
- ✗ agent-state/pm.json (no update_runtime_state tool)
- ✗ agent-state/pm-todo.json (no write_todolist tool)
- ✗ history/prd-rev-001.html (no archive_doc tool)
- ✗ timeline.ndjson 'prd_drafted' event (no timeline_append tool)
- ✓ core PRD site IS produced — sufficient to prove pipeline

──── code ────

- scripts/real-pm-smoke.js — loads root .env via dotenv resolved
  from server/node_modules (script dir has no node_modules of its own).

──── ambient ────

Files modified by user/linter while real-CLI work was in flight; merged
without revert:
- server/routes/devloop.js — new GET /:pid/requirements endpoint
- server/services/devloop/path-resolver.js — listProjects() includes
  archived flag + helpers; supports project archive lifecycle
- server/services/devloop/git-vault.js — commit() now accepts files[]
  to scope which paths the commit covers (avoids dragging linked-existing
  user's unstaged files into chore commits)
- server/src/core/devloop/loop-controller.js — createProject uses
  explicit files:['project.json','timeline.ndjson'] for first chore
  commit (avoids same issue)
- server/tests/devloop/path-resolver.test.js — coverage for archive/
  patch/hardDelete helpers
- web/src/components/devloop/RequirementListSection.vue (new)
- web/src/views/DevLoopNewRequirement.vue (new)
- web/src/views/DevLoopDashboard.vue — mounts RequirementListSection
- web/src/views/DevLoopProjects.vue — list page polish
- web/src/router/index.js — adds /devloop/:pid/requirements/new route
- web/src/components/devloop/DashboardHeader.vue — back link tweak

Test results: 233/233 vitest pass (was 230 → +3 path-resolver cases).

──── ⚠ SECURITY NOTE ────

.env is currently TRACKED in git (committed in b1a348b) even though
.gitignore lists it. Existing committed contents include credentials for
DOUBAO / FEISHU / GITHUB / GOOGLE / JWT. The CLAUDE_CODE_OAUTH_TOKEN +
AZURE_OPENAI_API_KEY I just added to .env are NOT in this commit — they
stay in your working tree only.

Recommended follow-up (separate commit):
  git rm --cached .env
  git commit -m "chore: stop tracking .env (already gitignored)"
And rotate every key that was in the previous committed .env.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Two parallel pieces of plumbing — neither has been exercised end-to-end yet
(real CLI gated on `claude /login`; Projects list view served alongside
existing pages):

──── real-CLI wire-up (REAL.1 + REAL.2) ────

LemonBoss now has a clean toggle between mock & real Claude CLI:

- packages/acp-core/protocol/ClaudeCliProtocol.js
  * `options.systemPrompt` → `--append-system-prompt <prompt>` so each
    devloop agent receives its role-specific prompt.md without losing
    Claude's default tool-use conventions.
  * `options.maxBudgetUsd` → `--max-budget-usd` (note: only effective in
    `--print` mode; documented inline).

- server/src/core/devloop/loop-controller.js
  * callAgent now branches on `opts.mock`:
    - mock (P1-P5 path, untouched): fixture sequence + `mock/files` event
    - real: read system/templates/{agent}/prompt.md, pass as systemPrompt,
      snapshot project file mtimes pre-call, diff post-call to compute
      `files_written` — no fixture, no mock/files needed.
  * `_snapshotMtimes(root)` helper walks the project tree (skipping
    .git / node_modules / .cache / .tmp) and returns Map<relPath,mtime>.
  * timeline event payload now carries `real: true` flag.

- scripts/real-pm-smoke.js — minimal real-CLI sanity:
  spawns claude, injects PM prompt, prints which files were written +
  git commit sha. Hard timeout 5min. Single agent → expected spend
  $0.10-0.30 per run when authenticated.

Current status: process spawn + system-prompt injection + stream-json
flow all verified up to the `Not logged in · Please run /login` gate.
Auth is the only remaining blocker for executing the real smoke.

──── project CRUD routes ────

server/routes/devloop.js + server/services/devloop/path-resolver.js
add the lifecycle pieces the Projects list view needs:

- GET    /projects?include_archived=true   list w/ archive filter
- PATCH  /projects/:pid                    edit name + idea_summary
- DELETE /projects/:pid                    soft delete (archive)
- DELETE /projects/:pid?hard=true          hard delete (rm -rf sandbox;
                                            unregister linked)
- POST   /projects/:pid/restore            un-archive

path-resolver exposes matching helpers: listProjects({includeArchived}),
patchProjectMeta(pid,patch), hardDeleteProject(pid).

──── UI ────

- web/src/views/DevLoopProjects.vue (320 lines, new)  — Projects list
- web/src/router/index.js — adds `/devloop` → DevLoopProjects
- web/src/components/devloop/DashboardHeader.vue — back-link now points
  to `/devloop` (project list) instead of `/company`.

──── housekeeping ────

- CLAUDE.md / start.sh — start.sh now boots server/index.js (full route
  surface incl. /api/devloop) instead of the historical agent-server.js;
  docs updated to reflect this.

──── tests (+12) ────

- server/tests/devloop/routes-crud.test.js — 12 cases:
  PATCH validation (4) · soft DELETE + list filter (4) · POST /restore
  (1) · hard DELETE (2) · GET /projects default behavior (1).

Results:
- phase0-verify .. phase5-verify: 8+7+7+6+9+9+7 all pass
- vitest devloop+acp-core: 230/230 (was 218 → +12)

Specs:
- docs/prd/newfunction/_spec/arch-acp-bridge.md · Mock Mode
- docs/prd/newfunction/_spec/plan-migration.md · "自举乐趣" (real path
  prep)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Self-bootstrap demo: hits the same HTTP API a human would, asking
DevLoop to add a /restart endpoint to itself. End-to-end:
  1. POST /projects  (PM + Architect scaffold)
  2. GET  /state
  3. POST /run        (L1 + L2 → ship)
  4. GET  /{bugs,timeline,changelog,units/todo-be}
  5. POST /feedback   (PM incremental → PRD rev 1→2)
  6. POST /run        (re-ship)
  7. POST /sign-off   (→ shipped-final)
  8. POST /feedback   (→ 400 InvalidProjectStatusTransition)

Run: node scripts/self-bootstrap.js (artifacts retained for inspection)

Output proves the three-layer Loop survives a real curl-equivalent
session: 12 git commits auto-generated, 20 timeline events emitted,
prd_rev bumped, sdd_rev unchanged (happy path), bugs.ndjson empty
(no integration failures), .git contains full agent provenance.

For production: drop LEMONBOSS_CLAUDE_MODE=mock — the protocol layer
will route to real Claude CLI without any code change in
LoopController / routes.

Specs: docs/prd/newfunction/_spec/plan-migration.md · "自举乐趣"

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…b-pages + UI endpoints)

Completes the §P4 acceptance UI scope that was deferred in commit
0594b1d. Adds the full Vue Dashboard + Ops sub-pages with live SSE
stream + auto-reconnect, unit DAG with detail drawer, PRD/SDD diff
panel, feedback modal, and 4 ops views (Bugs / Loops / Changelog /
Progress).

Vue surface (≈1480 lines):
- web/src/views/DevLoopDashboard.vue (~110 lines)
  * 4-region grid: status header / loop bar / units DAG / live stream /
    PRD diff. Polls /state every 2.5s; opens feedback modal & unit
    drawer; mounts Sign Off / Abandon controls.
- web/src/views/DevLoopOps.vue (~50 lines) — tab container.
- web/src/components/devloop/DashboardHeader.vue
  * Status badge (7 states color-coded), NEW REQUIREMENT button,
    Sign Off / Abandon buttons (disabled per FSM), Ops nav link.
- web/src/components/devloop/LoopStatusBar.vue
  * 4-phase pipeline (Docs → L1 → L2 → Ship), highlights active phase.
- web/src/components/devloop/UnitsDAG.vue
  * SVG DAG rendered from topological waves; per-unit status color;
    click → emits select → opens UnitDrawer.
- web/src/components/devloop/UnitDrawer.vue
  * Slide-in panel showing unit metadata + last 3 runs + result
    summary + coder.log tail (last 1KB).
- web/src/components/devloop/LiveAgentStream.vue
  * EventSource subscriber listening to project.status,
    unit.state, integration.result, triage.result, sdd.updated,
    prd.updated, human_intervention_needed, etc. Manual 5s reconnect
    on disconnect (browser's built-in Last-Event-ID is honored).
- web/src/components/devloop/PrdDiffPanel.vue
  * Reads changelog.ndjson, renders prd_rev / sdd_rev entries with
    trigger labels.
- web/src/components/devloop/FeedbackModal.vue
  * POSTs /feedback with PM incremental — shows rev bump on success.
- web/src/components/devloop/ops/BuglistView.vue
  * Filterable bug table; status badges; severity / category columns.
- web/src/components/devloop/ops/LoopLogView.vue
  * Timeline grouped by L1 (unit.*) / L2 (integration/triage/sdd/l2_*) /
    L3 (project.status/shipped/prd.updated/human_intervention) /
    System (rest). Free-text substring filter.
- web/src/components/devloop/ops/ChangelogView.vue
  * Tabular prd_rev/sdd_rev entries with by/trigger/summary columns.
- web/src/components/devloop/ops/ProgressView.vue
  * 6 metric cards (status, PRD rev, SDD rev, units passed bar,
    L2 rounds bar, open bugs) + per-unit breakdown table.

Router:
- web/src/router/index.js — adds:
  * /devloop/:pid              → DevLoopDashboard
  * /devloop/:pid/ops/:tab(bugs|loops|changelog|progress) → DevLoopOps

Backend UI-supporting endpoints (server/routes/devloop.js):
- GET /api/devloop/projects/:pid/timeline?limit=N
    Reads timeline.ndjson, returns last N events reversed.
- GET /api/devloop/projects/:pid/changelog
    Returns full changelog.ndjson entries reversed.
- GET /api/devloop/projects/:pid/units/:unitId
    Returns { unit, runs (last 3 result.json), coder_log_tail }.
    404 on unknown unit.

Tests (+5 cases):
- server/tests/devloop/routes.test.js — new P5 UI endpoints block:
  * timeline / changelog / units happy-paths
  * 404 on unknown unit and unknown pid

Acceptance:
- scripts/phase5-verify.js — 7 steps:
  ① Vue build artifacts (DevLoopDashboard.js + DevLoopOps.js chunks)
  ② POST /projects → state returns status + units
  ③ GET /timeline returns events
  ④ GET /changelog returns entries
  ⑤ GET /units/todo-be returns unit + runs
  ⑥ GET /bugs returns bug list
  ⑦ SSE /stream delivers ≥1 event after a triggering feedback POST

Vue build:
- npm run web:build → DevLoopDashboard chunk 15.63 kB,
  DevLoopOps chunk 9.09 kB, both with co-loaded CSS bundles.

Results — all 7 phase gates green:
- phase0-verify: 8/8
- phase0-test-call: 7/7
- phase1-verify: 7/7
- phase2-verify: 6/6
- phase3-verify: 9/9
- phase4-verify: 9/9
- phase5-verify: 7/7
- vitest devloop+acp-core: 218/218 (was 213 → +5)

Specs: docs/prd/newfunction/_spec/plan-migration.md · P4 L3 + UI

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Implements the §P4 acceptance gate from plan-migration.md, with one
scope adjustment confirmed up-front: full Vue Dashboard (~1650 lines)
deferred to a future UI phase, replaced by extending the existing
P3 static status page with Sign Off / Abandon / Feedback controls.
All P4 backend acceptance criteria are scripted (phase4-verify.js).

Project status FSM (project.json.status):
- server/src/core/devloop/loop-controller.js
  * draft  →  running  →  shipped  →  shipped-final | abandoned
                ↓             ↓
          l2_blocked    (feedback flips back to running)
          l2_exhausted
  * `_setProjectStatus` validates transitions via STATUS_TRANSITIONS,
    emits SSE `project.status`, writes timeline event.
  * createProject seeds status=draft; runDocsPhase end → running;
    runProject(shipped) → shipped; all dead-end branches (l2_blocked,
    l2_exhausted) also propagate to status via _safeSetStatus.

L3 helpers:
- signOff(pid, opts) — requires status=shipped → shipped-final; commits
  a `chore: sign-off` git entry; rejects other source states with
  InvalidProjectStatusTransition.
- abandon(pid, opts) — any non-terminal → abandoned; commits + calls
  sseBroker.close(pid) to send SSE close frame to subscribers.
- submitFeedback(pid, text, opts) — rejects in shipped-final/abandoned;
  invokes PM in incremental mode; on prd_rev bump writes
  changelog.ndjson prd_rev entry + emits prd.updated SSE; if prior
  status was shipped, flips back to running so next runProject can
  rebuild.

PM incremental mock fixture:
- fixtures/devloop-mock/devloop-pm.json — converted to sequence form:
  * sequence[0] (init) — original P1 fixture (PRD rev=1, 14 files).
  * sequence[1] (incremental) — appends a new section to
    prd/feature/feature-tree.html, bumps article data-rev to 2,
    writes history/prd-rev-002.html.

Baseline happy-path Integrator:
- fixtures/devloop-mock/devloop-integrator.json — single-shot pass.
  Makes vanilla runProject ship without a scenario override.

P4 happy-path scenario:
- fixtures/devloop-mock-scenarios/happy_path/devloop-architect.json —
  single-unit (todo-be only) Architect so end-to-end ship works with
  the baseline Coder/Tester (which only know todo-be paths).

Routes:
- server/routes/devloop.js:
  * POST /projects/:pid/sign-off — 400 InvalidProjectStatusTransition
    when status != 'shipped'; 200 returns { status }.
  * POST /projects/:pid/abandon  — body { by?, reason?, note? }; 400 on
    terminal state; 200 returns { status: 'abandoned' }.
  * POST /projects/:pid/feedback — body { text (req), by?,
    mockFixtureDir? }; 400 on missing text or shipped-final/abandoned;
    200 returns { prd_rev_before, prd_rev_after, status }.
  * POST /projects: now accepts optional `mockFixtureDir` so the same
    fixture dir threads through both the create call and later
    feedback (keeps mock-sequence counters aligned).

Static status page (replaces full Vue Dashboard for P4):
- server/public/devloop-status.html — adds:
  * Status badge in header (color-coded per status).
  * Sign Off / Abandon control buttons (disabled per current state).
  * Feedback textarea + Submit button → POST /feedback.
  * Buttons reflect FSM (signoff only when shipped; abandon/feedback
    locked at terminal states).

Acceptance:
- scripts/phase4-verify.js — 9 steps, full HTTP path:
  ① POST /projects → running
  ② POST /run → shipped
  ③ POST /feedback → PRD rev 1→2 + running (+ changelog entry)
  ④ POST /run again → shipped
  ⑤ POST /sign-off → shipped-final
  ⑥ POST /feedback (after sign-off) → 400
  ⑦ POST /sign-off (after sign-off) → 400
  ⑧ second project: POST /abandon → abandoned
  ⑨ POST /abandon (after abandon) → 400

Tests (+19 cases):
- server/tests/devloop/p4-l3-feedback.test.js
  * 14 FSM cases covering happy path + abandon path + signOff
    pre-conditions + empty feedback rejection.
  * 5 route cases via fetch on ephemeral express app.

Results:
- phase0-verify: 8/8
- phase0-test-call: 7/7
- phase1-verify: 7/7
- phase2-verify: 6/6
- phase3-verify: 9/9
- phase4-verify: 9/9
- vitest devloop+acp-core: 213/213 (was 194 → +19)

Spec deviations explicit:
- Full Vue DevLoopDashboard.vue + Ops 4 sub-pages NOT implemented;
  static status page handles the demoable surface area instead.
- All backend endpoints from §P4 (sign-off, abandon, feedback) are
  complete and tested.

Specs: docs/prd/newfunction/_spec/plan-migration.md · P4 L3 + UI

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Implements the §P3 acceptance gate from plan-migration.md: a single
POST /api/devloop/projects/:pid/run drives the full project from L1
through L2 with 4 distinct BugTriager branches, observability via SSE
stream + bugs.ndjson + changelog.ndjson, and a tiny static status page.

Mock protocol — fallback dir:
- packages/acp-core/protocol/ClaudeCliProtocol.js
  * New options.mockFallbackDir: when scenario dir lacks a per-agent
    fixture, fall back to the baseline fixtures/devloop-mock/.
    Enables scenario dirs to override only the agents that differ
    (Integrator + Triager + sometimes Architect).

Scenario fixtures — 4 L2 branches:
- fixtures/devloop-mock-scenarios/contract_mismatch/
  * Architect: sequence[init, patch] — patch bumps sdd_rev → 2,
    units.json l2_rounds → 1, marks todo-be back to pending.
  * Integrator: sequence[fail (500 vs 201), pass].
  * Triager: contract_mismatch confidence 0.85 with proposed_sdd_patch.
- fixtures/devloop-mock-scenarios/impl_bug/
  * Integrator: sequence[fail (ReferenceError), pass].
  * Triager: impl_bug confidence 0.78 affected=[todo-be], proposed=null.
- fixtures/devloop-mock-scenarios/spec_ambiguous/
  * Triager: confidence 0.4 → LoopController emits human_intervention.
- fixtures/devloop-mock-scenarios/infra_flake/
  * Integrator: sequence[crashed (EADDRINUSE), pass].
  * Triager: infra_flake confidence 0.95 affected=[].
- Each scenario also includes a 1-unit (todo-be) Architect.init fixture
  so baseline Coder/Tester (todo-be) can drive L1.

LoopController:
- server/src/core/devloop/loop-controller.js — adds:
  * runProject(pid, opts) — wave-scheduled L1 via _groupUnitsByWave,
    runIntegrator (devloop-integrator), runTriager (devloop-triager),
    then branch dispatch:
      - contract_mismatch+conf≥0.5 → Architect(patch) writes new
        units.json (already pending, l2_rounds++); emits sdd.updated +
        changelog sdd_rev entry; loop back to L1.
      - impl_bug+conf≥0.5 → unitRegistry.reset(affected); loop, no
        budget burn.
      - spec_ambiguous OR conf<0.5 → emit human_intervention_needed
        SSE, exit l2_blocked.
      - infra_flake → loop directly (no reset, no budget burn).
  * runDocsPhase + runUnit + callAgent all thread opts.mockFixtureDir
    through to the protocol.
  * Auto-attaches sseBroker to unit-registry and bug-tracker on module
    load — every FSM transition + bug op fires an SSE event.
  * bug_open at integration failure, bug_transition → fixed when
    subsequent L2 round passes.

Routes:
- server/routes/devloop.js:
  * POST /projects/:pid/run now defaults to full runProject; ?only=<id>
    still drills into single-unit runUnit (P2 compatibility).
  * GET  /projects/:pid/stream — SSE with Last-Event-ID replay.
  * GET  /projects/:pid/bugs?status=&unit_id=&severity= — bug list.
- server/index.js + agent-server.js mount /public for static assets.

Static status page:
- server/public/devloop-status.html (~100 lines) — pure HTML, polls
  GET /state every 2s, renders unit DAG with status pills + timeline
  tail. URL ?pid= or input box.

Acceptance:
- scripts/phase3-verify.js — 9 steps across 4 scenarios + observability:
  ① contract_mismatch ships at sdd_rev=2 l2_rounds=1, sdd.updated SSE,
    changelog sdd_rev entry, bug open → fixed.
  ② impl_bug ships, sdd_rev=1, l2_rounds=0 (no budget burn).
  ③ spec_ambiguous → l2_blocked + human_intervention_needed SSE.
  ④ infra_flake ships, rerun_integrator action, l2_rounds=0.
  ⑤ Observability: timeline/bugs/changelog/stream.log present.
  ⑥ SSE replay from Last-Event-ID returns ≥2 historical events.

Tests (+13 cases):
- server/tests/devloop/run-project.test.js (11) — 4 scenarios end to
  end + SSE event capture.
- server/tests/devloop/routes.test.js (+2) — full-project mode + bugs
  404. Updated P2 ?only stub test → full-project 404 on unknown pid.

Results:
- phase0-verify: 8/8
- phase0-test-call: 7/7
- phase1-verify: 7/7
- phase2-verify: 6/6
- phase3-verify: 9/9
- vitest devloop+acp-core: 194/194 (was 181 → +13)

Specs:
- docs/prd/newfunction/_spec/plan-migration.md · P3 验收
- docs/prd/newfunction/_spec/loops-l2.md (failure attribution + budget)
- docs/prd/newfunction/_spec/agents-integrator.md
- docs/prd/newfunction/_spec/agents-triager.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Implements the §P2 acceptance gate from plan-migration.md: a single
POST /api/devloop/projects/:pid/run?only=todo-be drives the L1 inner
loop (Coder → Tester → fail → Coder → Tester → pass), with the second
Coder pass demonstrably reflecting on the first failure.

Mock protocol — stateful sequences:
- packages/acp-core/protocol/ClaudeCliProtocol.js
  * Mock fixtures now support `sequence: [{chunks,result,files}, ...]`.
    Each protocol.connect() + sendPrompt() consumes the next variant;
    sticks on the last entry after exhausted.
  * Static `ClaudeCliProtocol.resetMockState()` clears counters between
    test runs.

Fixtures:
- fixtures/devloop-mock/devloop-architect.json — units.json now has
  status:pending + retries:0 + retry_budget per unit, plus
  units/{todo-be,todo-db,todo-fe}/spec.json so Tester has acceptance
  criteria to read.
- fixtures/devloop-mock/devloop-coder.json — sequence: implement (with
  intentional missing 400 branch) → retry (reflective fix, coder.log
  attempt:2 has last_failure/last_cause/this_fix/rationale).
- fixtures/devloop-mock/devloop-tester.json — sequence: fail (1/3
  failure with hint pointing at missing body validation) → pass (3/3).

LoopController:
- server/src/core/devloop/loop-controller.js — adds:
  * runUnit(pid, unitId, opts) — drives the L1 loop via unit-registry
    FSM (pending → coding → testing → failed → coding → testing →
    passed/blocked). Calls Coder then Tester per attempt; on failure,
    builds a retry context summarizing prior coder.log + tester
    failures and feeds it into the next Coder prompt.
  * _buildRetryContext + _findLatestTesterResult helpers.
  * callAgent now rewrites units.json.project_id to the real pid after
    mock writes (so unit-registry validation passes).

Route:
- server/routes/devloop.js — adds POST /projects/:pid/run?only=<unitId>.
  Without ?only, returns 501 (full project run lands in P3).

Acceptance:
- scripts/phase2-verify.js — 6 steps:
  1. POST /projects (PM + Architect)
  2. POST /run?only=todo-be returns ok=true, attempts=2, final=passed
  3. FSM trail matches expected 6-step transition sequence
  4. coder.log second entry has all 4 reflection fields
  5. runs/ has ≥2 result.json with first.ok=false, last.ok=true
  6. sandbox cross-unit + prd writes blocked by ToolSandboxError

Tests (5 new cases):
- server/tests/devloop/run-unit.test.js (4) — FSM trail, coder.log
  reflection, runs/ result chain, sandbox enforcement.
- server/tests/devloop/routes.test.js (+3) — POST /run validation,
  full P2 loop, 404 on unknown unit.

Results:
- phase0-verify: 8/8
- phase0-test-call: 7/7
- phase1-verify: 7/7
- phase2-verify: 6/6
- vitest devloop+acp-core: 181/181 (was 174 → +7)

Specs:
- docs/prd/newfunction/_spec/plan-migration.md · P2 验收
- docs/prd/newfunction/_spec/loops-l1.md (retryWithReflection)
- docs/prd/newfunction/_spec/agents-coder.md
- docs/prd/newfunction/_spec/agents-tester.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Implements the §P1 acceptance gate from plan-migration.md: a single
POST /api/devloop/projects produces a runnable todo-demo project with
multi-page PRD/SDD sites, units.json, integration spec, agent-state,
and history snapshots — all via mock agents (no real Claude CLI cost).

Code additions:
- packages/acp-core/protocol/ClaudeCliProtocol.js
  * mock mode now emits an extra `mock/files` acp_event when the fixture
    contains a files[] array. LoopController applies it to the project
    root, letting mock agents produce real outputs.
- server/src/core/devloop/loop-controller.js (now ~280 lines)
  * callAgent(pid, agentName, prompt, opts) — single-agent invocation:
    reads system/templates/{agent}/prompt.md, runs mock protocol,
    applies fixture files[], timeline-logs, auto-commits.
  * runDocsPhase(pid, requirement) — orchestrates PM → Architect with
    `docs.complete` timeline marker.
  * getProjectState(pid) — returns project.json + units + prd_rev/sdd_rev
    + timeline tail for the GET /state endpoint.
- server/routes/devloop.js (new)
  * POST /api/devloop/projects — createProject + runDocsPhase
  * GET  /api/devloop/projects
  * GET  /api/devloop/projects/:pid/state
- server/index.js / server/agent-server.js — mount /api/devloop.

Mock fixtures (drive the full acceptance file tree):
- fixtures/devloop-mock/devloop-pm.json
  * 14 files: prd/{index,reading-guide,product/*,feature/*,flow/*,prototype/*}.html,
    prd/assets/{shell.css,shell.js,search-index.json},
    agent-state/{pm.json,pm-todo.json}, history/prd-rev-001.html.
- fixtures/devloop-mock/devloop-architect.json
  * 13 files: sdd/{index,mvcp/*}.html, sdd/assets/*,
    units.json (3 units, DAG), integration/spec.json,
    agent-state/{architect.json,architect-todo.json}, history/sdd-rev-001.html.

Acceptance:
- scripts/phase1-verify.js — spins ephemeral express app, POSTs the
  todo-demo project, asserts 23 expected paths exist + 3 units with
  l2_rounds/l2_budget + git ≥4 commits + timeline events.

Tests (12 new cases):
- server/tests/devloop/loop-controller.test.js (7) — callAgent +
  runDocsPhase + state.
- server/tests/devloop/routes.test.js (5) — POST validation, full
  POST, GET state, 404 on unknown pid.

Results:
- phase0-verify: 8/8
- phase0-test-call: 7/7
- phase1-verify: 7/7
- vitest devloop+acp-core: 174/174 (was 162 → +12)

Specs: docs/prd/newfunction/_spec/plan-migration.md · P1 Docs MVP

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Final P0 deliverables to make the system bootable in mock mode and
pass `scripts/phase0-verify.js` + `scripts/phase0-test-call.js` end-to-end.

ClaudeCliProtocol (mock mode):
- LEMONBOSS_CLAUDE_MODE=mock or { mock: true } in constructor enables
  mock mode. connect() becomes a no-op; sendPrompt reads fixtures from
  fixtures/devloop-mock/{agentName}.json and emits scripted session_update
  chunks + session/result(mock=true). Falls back to default.json.

Agent registry:
- 6 entries added to system/templates/_registry.json (devloop-pm,
  devloop-architect, devloop-coder, devloop-tester, devloop-integrator,
  devloop-triager).
- Per-agent dirs system/templates/devloop-{role}/ with:
  * prompt.md   — auto-extracted from agents-{role}.html §2.2
  * config.json — cli.toolPolicy.allowedTools + sandbox.writeAllowList

Tooling:
- scripts/extract-agent-prompts.js  — regex-extracts §2.2 system prompts
  from 6 agent HTML pages to system/templates/devloop-{role}/prompt.md.
- server/src/tools/devloop/index.js — central export (tools Map,
  bashHooks, dispatch).
- server/src/core/devloop/loop-controller.js (P0 skeleton) — exposes
  createProject (sandbox alloc + git init + first commit + timeline) and
  commitAfterAgent (per-agent kind-routed git commit + timeline event).

Mock fixtures:
- fixtures/devloop-mock/default.json + devloop-pm.json

Acceptance scripts:
- scripts/phase0-verify.js   — 8 static checks (35 tools loadable,
  6 agents registered, prompt+config wired, bash guard exported, services
  require, fixtures present, git-vault interface, loop-controller).
- scripts/phase0-test-call.js — 7 end-to-end steps under mock mode
  (createProject → CLI connect → sendPrompt chunks → no-op commit returns
  null → real write commits → git log ≥2 → timeline has both events).

vitest.config.js: include packages/**/*.test.js so the mock smoke test
runs in the suite.

Results:
- 162/162 devloop + acp-core tests pass (up from 159).
- phase0-verify: 8/8.
- phase0-test-call: 7/7.

Specs: docs/prd/newfunction/_spec/plan-migration.md · Quick-Start step 7

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Adds the DevLoop Agent tool layer (CommonJS) under server/src/tools/devloop:
- _errors.js / _sandbox.js — shared infra (3 error classes + path allow-list w/ {unitId})
- tool-registry.js — loadAllTools / dispatch / listToolNames / getDevLoopTools
- persistence-tools.js (5) — write_todolist · update_todo_item · update_runtime_state · timeline_append · record_memory
- doc-tools.js (12) — bootstrap_prd_site · bootstrap_sdd_site · write_chapter · write_mvcp_page · archive_doc · diff_html · diff_units · echo_diff · update_search_index · validate_prd_site · validate_sdd_consistency · hash_contract
- coder-tools.js (3) — contract_bridge · sandbox_check · append_coder_log (retry fields required)
- tester-tools.js (5) — parse_vitest · hint_builder · bug_open · bug_transition · bug_list
- integrator-tools.js (6) — port_picker · spawn_units · health_wait · run_case · parse_placeholder · collect_stderr
- triager-tools.js (4) — extract_evidence · category_classifier · diff_contract_vs_impl · find_similar_bug
- bash-json-guard.js — preExecute hook blocking inline JSON in Bash (CLAUDE.md L91-99)

Total: 35 callable devloop tools.

Tests: 88 cases across 9 files, all passing; combined with P0.0 services
suite the project now has 159 green tests.

Specs:
- docs/prd/newfunction/_spec/arch-tool-registry.md
- docs/prd/newfunction/_spec/agents-{pm,architect,coder,tester,integrator,triager}.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

First concrete code commit for DevLoop. Implements all 7 services that
P0.A tools will depend on, per plan-migration P0.0.

Services (server/services/devloop/, ~900 lines):
- path-resolver.js   foundation — resolveProjectRoot + 12 derived paths;
                     sandbox + linked-new mode support; sensitive path
                     blacklist (with /tmp + os.tmpdir() exemptions);
                     ~/.devloop/linked-projects.json registry
- doc-store.js       PRD/SDD multi-file site IO + cheerio validateHTML +
                     validateUnitsSchema + canonical-JSON hashContract
                     + automatic history/ archival
- unit-registry.js   FSM (M-2: pending→coding→testing→passed/failed/blocked);
                     l2GateOpen; diffUnits (added/changed/removed);
                     reset semantics for L2 + L3
- bug-tracker.js     bugs.ndjson append-only + dedupKey + P-9 transition
                     state machine + list/stats/history aggregation
- timeline-logger.js M-13 ProcessTimeline — append/read/tail;
                     summary truncate to 280; payload oversize → ref form
- changelog-writer.js M-15 — append/read/latest for prd/sdd/units revs
- sse-broker.js      per-pid pub/sub + 25s heartbeat + stream.log replay
                     via Last-Event-ID; emit returns monotonic id
- git-vault.js       spawn-git wrapper — init/commit/tag/log/diff/status/
                     resetWorkingTree/revert/archive; per-pid mutex;
                     nothing-to-commit returns {skipped:true} not throw

Tests (server/tests/devloop/, 71 passing):
- path-resolver.test.js  (17 cases) — sensitive path · sandbox alloc · linked-new
- doc-store.test.js      (12 cases) — validateHTML · validateUnitsSchema · hashContract
- unit-registry.test.js  (15 cases) — FSM transitions · l2GateOpen · diffUnits
- bug-tracker.test.js    (10 cases) — open dedup · transition · list filter · history
- timeline-logger.test.js (9 cases) — append/read/tail · summary truncate · oversize
- git-vault.test.js      (8 cases)  — init idempotent · commit · tag · status · archive

vitest config (`globals: true`) means tests use describe/it/expect globally,
no `require('vitest')` needed (and would fail under vitest 4).

Dep added: cheerio@^1.0.0 (used by docStore.validateHTML; HTML parsing).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Before P0 coding begins, the doc set was missing three things that would
have stalled implementation on day 3:

1. Day-1 Quick-Start (plan-migration top section)
   - 8-step "what command do I type first" walkthrough
   - pnpm install → cp .env.example → extract-manifest verification → P0.0
     services → MOCK_CLAUDE=1 phase0-verify → real phase0-verify → P1
   - Anyone cloning can reach step 4 (doc verification) immediately

2. P0.0 服务层 7 件套 (plan-migration P0 子任务表)
   - Previously P0.A "工具实现" depended on docStore/unitRegistry/sseBroker/
     bugTracker/timelineLogger/pathResolver/GitVault but none were listed
     as a task — engineer would hit "docStore.writePRD doesn't exist"
   - Now P0.0 lists them as a sequenced 4.5-day task: pathResolver first
     (everyone depends on it), then 5 other services, finally GitVault
   - GitVault tasks consolidated into P0.0 (removed duplicate P0.I)
   - Total P0: 13.5 → 17 days (3 → 3.5 weeks)

3. Mock Claude CLI Mode (arch-acp-bridge §⑦, NEW)
   - MOCK_CLAUDE=1 env toggles ClaudeCliProtocol to read stubs from
     system/mock-responses/{agent}/{mode}.json instead of real Claude
   - Mock JSON: array of steps (text emit / tool_use), $pid placeholder
   - When mock vs real: mock for dev + CI, real for prompt quality + P1+
   - Enables zero-token tool dev + phase0-verify
   - Sections renumbered (⑧ → ⑨ etc) to accommodate insertion

Total project: 10 → 10.5 weeks (still honest, still includes everything).
No new MVCP defs (54). Search index 195.7KB. _spec/ regenerated by hook.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

The 50-page PRD HTML totals ~520KB; loading it all costs Claude ~222K
tokens just for context. This adds a token-efficient sibling layer:

- scripts/extract-spec.js → npm run spec:extract / spec:check
  Walks docs/prd/newfunction/*.html and produces stripped MD into _spec/.
  Strategy varies per page (full-extract for SDD/process/data,
  shell-strip for agents to keep long system prompts intact).
  Result: 327.9KB MD (~84K tokens) — 38% of full load, saves ~138K tokens
  for every Agent invocation that reads the spec.

- scripts/git-hooks/pre-commit + scripts/install-hooks.sh
  Pre-commit guard: when any docs/prd/newfunction/*.html changes, the
  hook checks the corresponding _spec/*.md is up to date; fails commit
  if stale, telling user to `npm run spec:extract`. Auto-installed via
  package.json `prepare` script on `npm install`.

- docs/prd/newfunction/_spec/ (51 .md files + CONVENTIONS.md)
  Machine-readable mirror of HTML. Used by:
  - Coder/Architect/Tester agents when reading spec at runtime
  - External Claude Code sessions doing reproducibility
  - CI checks (npm run spec:check)
  NOT hand-edited; regenerated from HTML by extract-spec.js.

- CLAUDE.md: 1-line note directing future agents to read _spec/*.md
  preferentially, fall back to *.html only for wireframes/SVG/full
  human-readable context.

This is the user's pre-existing scaffolding that the previous commits
hadn't pulled in yet. Now tracked + enforced by hook.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fills the gap: where does a DevLoop project actually live, and how does a user
create one? Previous docs assumed everything goes under
data/companies/{cid}/projects/{pid}/ with no user control.

Design:
- A DevLoop "project" = one directory + project.json + git history;
  the directory is the project root, the anchor for everything
- 3 modes:
  - sandbox (default, v1): root auto-generated under data/.../projects/{pid}/
  - linked-new (v1): user picks any empty path, e.g. ~/code/auto-todo
  - linked-existing (v2): bind to existing git repo subdirectory
- 3 creation entry points:
  - REST: POST /api/devloop/projects with optional {mode, target_path}
  - CLI: scripts/devloop-new.js with --path / --name / --requirement / --list
  - UI: Dashboard "+ NEW PROJECT" modal with mode radio + path picker
- New pathResolver service (path-resolver.js): single source of truth for
  resolveProjectRoot(pid). All paths derive from it; nothing hardcodes
  data/companies/... anymore
- linked projects registered in ~/.devloop/linked-projects.json
- memory stays at company level (~/data/companies/{cid}/memory/) even for
  linked projects — privacy + cross-project knowledge isolation
- Strict sandbox: blacklist /, /etc, /System, ~/.ssh, ~/.aws etc. for
  target_path; writeAllowList relative to root_path

Pages changed:
- arch-project-root.html (NEW, 15-section comprehensive design)
- sdd-model.html       (M-1 ProjectMeta + mode + root_path fields)
- sdd-control.html     (C-1 POST /projects accepts mode + target_path)
- assets/shell.js      (sidebar adds arch-project-root)
- assets/search-index.json + build-manifest.json (rebuilt)

Adds ~2 days to P0 (pathResolver + schema migration), ~1.5 days to P1
(CLI + mode params), ~1 day to P4 (UI modal). Total 10 → 10.5 weeks.

Key insight: linked-new mode means a user can DevLoop code straight into
~/code/auto-todo, then `git push origin main` to ship — without manually
exporting from the sandbox. The sandbox-vs-linked choice is path-transparent
to LoopController and all Agents.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fills a gap pointed out post-v0.3: docs had file-mtime + history/ archival
only, no real version control. Now every Agent that completes work triggers
LoopController to git commit; project ship/sign-off/abandon tag the repo.

Design:
- One git repo per project at data/companies/{cid}/projects/{pid}/.git
- LoopController-centralized commits (Agents stay sandboxed, no git access)
- Commit cadence: each Agent success → commit; Tester red → no commit;
  shipped/sign-off/abandon → tag
- New GitVault service (C-18): spawn-git wrapper, ~150 lines,
  init/commit/tag/log/diff/status/archive/revert/resetWorkingTree
- New process P-10 (Process.GitCommit): commitAfterAgent hook in
  callAgentWithPersistence; recoverOnBoot extended to detect dirty trees
- .gitignore excludes agent-state/ (high-write) + history/ (git is history)
  + stream.log + runs stdout (too large)
- New SSE events: git.committed · git.tagged · recovery_dirty_tree
- Defer git push-to-remote to v2 (no network deps in v1)

Pages changed:
- arch-git-versioning.html (NEW, comprehensive design, 16 sections)
- sdd-control.html       (+C-18 GitVault spec)
- sdd-process.html       (+P-10 commitAfterAgent + recoverOnBoot dirty-check)
- data-layout.html       (.git/ + .gitignore in project tree)
- plan-migration.html    (P0 +3 days for GitVault, total 10 weeks)
- assets/shell.js        (sidebar adds arch-git-versioning)
- assets/search-index.json (rebuilt, 189.5KB, 50 pages)
- build-manifest.json    (52 → 54 defs, 100% extraction)

Key benefit: Coder 3-retry chain can be `git diff`-ed; L2 fail allows clean
revert; project export becomes `git archive HEAD` (tracked files only,
not the ~30MB project dir).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Output of scripts/extract-manifest.js against docs/prd/newfunction/.
Captures the current state:
- 52 MVCP definitions (model=15, view=11, control=17, process=9)
- 100% path + shape extraction coverage
- Sized ~52KB

This file is regenerable (just run the script), but committing the
snapshot lets reviewers and external Claude Code sessions diff the
schema surface without rebuilding.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>