朱子纯 / erp-workflow-plugin

实跑打脸（xlyClaude13，2026-07-23）：4dea0e57 引入的冒烟集第 ③ 条规格写的是
「断言登录态有效（如页面出现仅登录后可见的导航元素）」，骨架照做生成了
`expect(getByTestId('user-box')).not.toHaveText(/未登录/)`。而该项目
`e2e/global-setup.ts` 写 storageState 时只写了 `erp_token`，`authSlice.ts` 却要求
`erp_token` + `erp_user` 两键齐备才回灌登录态——断言恒红。前端 test-gate 连跑 3 个
attempt（每次 7m17s，各含两遍建库副本）+ 仲裁循环，同代码同结果，证据文件三轮都写着
「重跑无法消除本失败」。冒烟集是增量模式下每轮必跑的那一份，它红一次就卡住整条流水线。

三处修正：

- **冒烟 ③ 改为只断言「没有被踢回登录页」**：带 storageState 访问需登录的路由，断言
  最终 URL 不是登录页 / 页面无登录表单。冒烟只回答「这份登录态被应用接受了吗」，
  **绝不**断言用户名、欢迎语、菜单项等 UI 文案——那依赖具体 auth 实现与文案，属业务
  e2e 范畴。补通用红线：三条用例都不得出现业务字面量、不得依赖演示种子具体行、
  不得随 FE 增减失效。冒烟红 = 栈或应用整体坏了，不该有第二种解读。

- **globalSetup 的 storageState 必须写「前端真正消费的完整登录态」**：生成前先 Grep
  frontend/src/ 定位 auth store 启动回灌读取的全部 key（token + 用户对象 + 权限等，
  键名各项目不同），一个都不能少，写完把读取键集与写入键集逐项对账登记 decisions[]。
  这是那个项目的真缺陷而不只是冒烟的问题——所有复用 storageState 的 e2e 都在未登录态
  下跑，表现为「元素找得到但内容是未登录态」这种极难归因的红。

- **冒烟集加契约版本标记 `// erp-smoke-contract: v2`**：原 state 判据只查冒烟集存不存在，
  坏的那份"存在"就永远判 exists:true 跳过重写，坏断言永久卡死。改为首行必须含 v2 标记，
  找不到即判 exists:false 强制骨架按新规格重建（同 prototypeCommit 的判据套路）。
  骨架自检也加一条：冒烟集逐条复核 + storageState 键集对账，别留到 test-gate 才炸。

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

起因：增量改一个功能仍会跑全量 e2e——用户改的功能与被跑的用例（如打印按钮那条）
毫无关系。实测 test-gate 占全流程墙钟 13.3%，且后端每个模块的 scripts/test.mjs
内部还会各跑一遍全量 playwright。

coding.mjs 新增 args.testScope（缺省 'affected'，逃生口 'full'）：

- **只收窄 e2e 段**。build / lint / 后端单测+集成 / 前端 vitest 一律仍全量——它们是
  分钟级的，却是编译期与逻辑回归的第一道网，砍掉省不下多少却漏掉最常见的连带破坏。
- 前端阶段 test-gate：范围 = 本轮待跑 FE 各自 plan 里 `测试先行类型 = e2e` 的
  test_file 并集（verify 段早有同款推导，line 659）；取不到则退冒烟集。
- 后端模块 test-gate（本轮无 FE 改动）：退到 frontend/e2e/__smoke__/ 冒烟集。
  不跳过 e2e 段——它同时是起栈健康检查。
- 首跑（全新项目）时「本轮待跑 FE」天然等于全部 FE，affected 与 full 重合；收窄只在
  /add-req 后的增量重跑里真的生效，这正是它存在的场景。

载体是 env ERP_E2E_SCOPE，**scripts/test.mjs 一个字未动**——它的 setup→build→lint→
test→e2e→promote→drop 是迁移晋升链路的契约，且模板改动不落已生成项目（见 preflight
硬门）；env 经 spawnSync 天然继承到 playwright 进程，前后端两条路径同一个开关。
消费端由 fe-skeleton 生成的 playwright.config 实现（未设=全量，绝不默认收窄），
同时生成与业务解耦的冒烟集；state 判据同步加严，存量项目会重跑一次骨架 stage 补齐。

防假绿（收窄的唯一真风险）：范围推导错的表现是「0 条用例 + exit 0」，与真绿不可区分。
GATE_SCHEMA 加 e2eScope/e2ePassed，编排层 guardEmptyE2e() 硬判——green 且明确 0 条一律
翻 red 走既有 retry/仲裁链。module-report 被要求如实记录本次范围，禁止拔高成「全量回归」。

新增 /erp-workflow:full-test（skills/coding/full-test）：跑 scripts/test.mjs 全链 +
显式清空 ERP_E2E_SCOPE 的全量 e2e，出 full-regression-<日期>.md 证据并提交。
前置硬门：工作树干净（绿后会晋升迁移到源库）、不与正在跑的 coding 流程撞端口。
后台子进程 + 回合内轮询；只跑测试、不改源码、红了只报告不修复。

代价明说：增量轮里跨功能连带回归（改共享组件 / router / 全局状态 / API 契约 / DB 迁移
打破没动过的功能）不再有网，由 /full-test 按需兜底。逃生口 testScope: "full"。

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

三项省时改造，都不改验收强度：

- prototype 渲染门幂等：证据头部钉一行 `- prototypeCommit: <哈希>`（git log -1 -- prototype/
  的**路径限定** tip，不是仓库 HEAD，否则任何无关提交都让判据失效），新增
  prototypePreviewStatePromptM 微步骤在 runPrototypePreview 开头比对，未变则整门跳过。
  本门原先无条件跑——一次增量里 resume 三次就渲染三次同一份原型（每次 3–7 分钟）。
  判不准一律 exists:false：过期截图基线会流到下游行为门比对，多跑一次只是几分钟。

- behavior carry 跨 run 复用：原先每个新 run 都从 behaviorRound=1 起步、入口无条件删掉整个
  frontend-phase/（含 carry），carry 永远活不过一次 run，每次 resume 重烧约 18 分钟重推导。
  拆成 mustReuse（同 run 后续轮，carry 必是本 run 刚写的 → 无条件复用）/ mayReuse（新 run 首跑，
  按 expectations.md 头部 carryScope + carrySpecs 短哈希比对 + 更新版本 spec 探测，通过才复用）。
  失效条件收敛于 spec——门的期望全部派生自 spec/prototype/docs05，两次 run 之间只有
  frontend/ 源码 fix。**运行栈仍每次冷起、库副本仍每次重建**，原纪律一字未动。

- Task 工具授权降级为既定约定：原文让每个 stage 用 ToolSearch select:Task 探测再按自主决策
  处理，同一个结论被反复探测、推理、登记——实测某项目 RESUME.md 2320 条决策里 123 条（5.3%）
  都在说这一件事，还随 handoff 反复读回上下文。现在直接写死「常态没有，用 Bash run_in_background
  detached 子进程即满足护栏意图」，不探测、不写 decisions[]、不升级、不 halt。
  adjudicatePromptM 补同口径的「已知非阻塞情形」——仲裁只套 microStepContract，拿不到 stage 侧
  授权，2026-06-13 曾自己复核后判 halt（BAC-DeliverMode-Query），42b6ed8e 只补了 stage 侧。

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

Router 下发的 feItems 一直是「缺 req-done/<FE> tag 的 FE」（见 routerPrompt），
但下游三处都按「项目全部 FE」解读，增量重跑（add-req 新增少数 FE）时后果实质：

- fe-skeleton：会把往轮已实现 FE 的路由改回 FeStub，等于把已验收功能打回占位态，
  行为门当回归红灯。改为两个清单分工——路由表覆盖按 docs/08 § 三全量声明（含已 [x]），
  只有本轮 feItems 指向 FeStub，清单外一律保留现有真组件指向；自检加一条
  git diff 查「真组件 → FeStub」误伤。
- behavior gate：断言作用域收敛到本轮清单；清单外路由（往轮已验收）记证据但不入分母、
  不记 coverageGaps，跨 FE 连带回归由阶段末 testGate 的全量 e2e 兜底。
- fe-skeleton 幂等判据只看本轮清单——拿全量当判据会在增量重跑时误判为缺、白跑一次骨架。

另修前端 e2e 连接竞态：后端起栈一直有「轮询健康端点」硬约束，前端 dev server 却从没被
规定由谁起、何时算就绪，生成的项目普遍「并行起 vite + 直接跑 playwright」。实测代价：
后端 testGate 连红 4 次（attempt 1-4 全是 dev server 未起 / 连接被拒，49 分钟），
第 5 次同代码变绿，还因此被误判成 flaky。现在 playwright.config 必须声明 webServer 段
（url + timeout ≥120s）或 globalSetup 显式轮询至可连；已存在但缺就绪门的**必须补齐**，
不属于「已存在就不动」的范围，state 判据同步从严。行为门 runner 侧补同口径就绪判定，
超时归 envError.kind="stack-not-ready" 走 retry，不记成 interactionFailures。

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

实测口径（同一 ERP 项目 13 次运行 / 1012 个子代理会话 / 2988 分钟，按子代理
transcript 首末 timestamp 统计）：test-gate 13.3%、module-report 11.7%（均值
14.6 分钟）、behavior 11.6%、tdd 合计 22.4%；微步骤 574 个会话只占 6.6% 时间
却占 57% 会话数。四项改动照此下刀。

1) ETA 播报（新增 STAGE_MIN / etaLog / itemMin / moduleMin）
   左侧 Phases 面板的分母是 harness 侧「已派生子代理数」，脚本无 API 预声明
   总量，串行链上只能 0/1→1/2 地长；运行时又禁 Date.now()（会破坏 resume
   重放），拿不到真实计时。故用 log() narrator 行按「剩余段数 × 实测分布」
   静态外推：STAGE_MIN 存各 stage 的 [p25, 中位数, p75]，etaLog 挂在
   runStage/runAction 的重试循环里，开跑与每次重跑各播一行「预计 / 再需
   X–Y 分钟」；gate / behavior 走 agentR，另在 attempt 级显式挂。表外的
   微步骤（0.2 分钟级）静默，不刷屏。纯显示，绝不参与控制流。

2) 微步骤合并（会话数）
   - docs/08 勾选 2 会话 → 1：原「读勾选态」与「写勾选+commit」之间没有任何
     JS 决策，纯白烧一次往返。合并为 flipDocs08CheckboxPromptM，三种非错误
     终态经 ACTION_RESULT 的 detail 回传（not-found / already-checked /
     flipped），调用方分支日志逐条对应。删 CHECKBOX_STATE_SCHEMA 与两个旧
     prompt。每个 REQ/FE 省 1 个会话。
   - 分支就位 3 会话 → 1：exists? → checkout|create → head 本是一条确定性
     git 链。合并为 ensureBranchCheckedOutPromptM + BRANCH_READY_SCHEMA
     （branch 必填 = 实测 HEAD，明写「据实回填、绝不改写成期望值」）。JS 侧
     HEAD 不符仲裁重切循环原样保留，合并只是它的第一次尝试。lane 模式不走
     这条（worktree add 已上分支）。每个模块省 2 个会话。
   - runAction 加可选 schema（缺省仍 ACTION_RESULT_SCHEMA），只要含 success
     布尔，失败/仲裁/重试语义一字不变。

3) module-report 瘦身
   原实现让报告子代理 Glob + 按 attempt 升序通读**全部** test-gate 证据（前端
   还要加全部 behavior-r*-a*.md）去自证「最后一份绿」——可红态根本走不到
   report（testGate / runBehaviorGate 会先 halt），JS 才是这个事实的第一手
   持有者。改为 testGate 返回 {...g, attempts}、runBehaviorGate 绿态返回
   {rounds, attempts, routes/controls/authState}，经 runModule 的 reportFacts
   透传给 reportPrompt(module, c, facts)：前置改成「门禁事实由编排层给定」，
   子代理只读点名的那一两份（末次 green；attempts>1 才加首次 red），flake
   标注也由 JS 判定后写死进 prompt。§ ⑤ / § ⑧ 的通配符通读同样收敛。

4) 行为门跨 round 复用（carry）
   实测本门 40+ 分钟里约 18 分钟花在「读 spec → 查表 → 反查组件 → 推导期望
   → 写 runner」，而 fix 只改 frontend/ 源码——期望（来自 prototype/REQ/
   docs05）与 runner（DOM/locator 驱动）在同一前端阶段内不失效。新增
   .tmp/behavior-gate/frontend-phase/carry/ 存 expectations.md + run.mjs +
   sentinel.sql 跨 round/attempt 存活：r1a1 全量推导后必须落 carry；r>1 或
   attempt>1 时 step1 / step4 整节跳过、sentinel 直接灌 carry 那份，只在有
   明确证据（runner 自身 bug / 路由表真变了）时增量修补并同步回 carry。
   不复用的部分写成硬约束：运行栈每次冷起、库副本每次重建、种子每次重灌、
   证据每轮独立文件——复用的只是「推导结果与脚本」。

验证：lib/check-workflow-syntax.mjs 语法门 + 悬空引用 grep 自检 + 把
behaviorGatePrompt / reportPrompt / 两个合并版微步骤用 stub 渲染出实际
prompt 眼验（含 reuse、flake、后端/前端各分支变体）。coding.mjs 无行为测试，
真实收益仍需目标项目实跑确认。

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

实跑暴露：行为门子代理生成的一次性 run.mjs 把 status 初始化为 'red' 后再未
赋值，恒红且不带任何分类信号。本轮靠子代理自己察觉才没误判，但 r1~r3 同样
失真——任何依赖该字段做判定的地方都会恒判红，且会撞上 runBehaviorGate 的
「red 无分类原因」守卫，被判 HALT behavior-red-unclassified。

根因在插件侧：behaviorGatePrompt 只说 runner 要「透传结构化结果」，从未规定
status 怎么算，生成方式完全放任。

契约补四条：
- status 必须由信号数组末尾一次性推导，判据与「输出」节逐字一致
- 变量初值用 null 或直接末尾 const，禁止 let status = 'red'/'green' 这类带
  默认值的声明（恒红比恒绿更隐蔽，看起来像门在严格把关）
- runner 输出前自检：red 必须有至少一条分类信号能解释；自检不过则非零退出，
  不要输出无法解释的 red
- 子代理返回的 status 必须等于 runner 自检后的值，不得手工改判；不一致是
  runner 的 bug，修 runner 重跑

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

Workflow 脚本自身无 fs / 无 shell（沙箱限制），git 只能经子代理跑——省不掉
"手"，但可以省"次数"。本次只动两类**纯查询**调用点，不碰任何验收语义、
不改错误处理粒度。

1a tag 全量预取：开跑时（Router 之前）一次 `git tag -l "req-done/*"
   "fe-code-done/*" "milestone/*"` 拉回全表建 Set，之后
   - featureLoop 入口 dedup（每 REQ / 每 FE 一次）
   - overlap phase1 dedup（每 FE 一次）
   - runMilestone tag 存在性（每模块一次）
   全部变成内存查表。tag 是仓库级 ref、worktree 间共享，一份全局快照对主根
   与所有 lane 同时成立。运行中新打的 tag 由 noteTag() 同步记账（脚本是唯一
   写入方，单线程 await 串行，不会漏；显式判 success，防日后加 allowContinue
   时把失败放行误记为已打）。

1b 默认分支 memo：refs/heads/main|master 是整程不变量且全仓共享，原本
   runBranchSetup / runMilestone / runCrossModule / prepareParallelWave /
   fe-overlap 五个调用点各起一次子代理探测，每模块至少查 3 次。改为首次探测
   后整程复用；探测失败不缓存，下次重试，保持原有 agentR 的 halt 语义。

以 5 模块 x 4 REQ + 8 FE 估算，两项合计省约 45 次子代理会话。

fail-safe：预取失败（子代理 null / 结果不合形）→ tagSnapshot 保持 null，
tagKnown() 返回 null，全部调用点自动回退到"每次一个子代理查"的现行路径，
语义一字不差，不新增任何 halt 点。

验证：lib/check-workflow-syntax.mjs 语法门通过；调用点配平经 grep 自检；
多 pattern `git tag -l` 语法在本机 git 上实测有效。coding.mjs 无行为测试，
真实验证需下一轮实跑。

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

缺陷：新建分支以默认分支为起点（createBranchFromPromptM），但复用已存在分支的
两条路径——主根 checkout（coding.mjs:2167 分支）与 lane worktree add（分支 2）——
都不带任何同步动作。上一轮跑完遗留的功能分支遂停在原位，其后进入默认分支的
REQ 卡片 / migration / docs 增量对本轮全部不可见。

实测后果（xlyClaude15DDD 2026-07-20）：module-CFG 停在旧点，spec 子代理报
「全仓 grep <req> 零命中」后照自身理解另实现了一套设计，直到 milestone merge
才以三文件内容冲突暴露，整轮返工。子代理并未跑偏——它被喂了残缺的世界。

修法：HEAD 确认后统一跑 syncBranchWithDefaultPromptM（lane / 主根共用）。
新建分支走到这里恒为 up-to-date，故可无条件执行、幂等。冲突时保留现场返回失败，
经 runAction 仲裁 halt 交人工——陈旧分支与默认分支真冲突意味着两边都动了同一处，
只有人能判断取舍；自动 abort 会抹掉这个信号，让下一轮再撞同一个坑。

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

AGT test-gate 三连 halt 根因:闸子代理把 test.mjs 派到后台后装 Monitor 结束回合等通知,
Workflow agent 语义里结束回合即完成,判「未调 StructuredOutput」halt;通知永远到不了.
在 featureStageContract 授权条目后追加硬约束,前后端闸/verify/tdd 等全部阶段同享.

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

存量项目（模板修复 56c4d891 之前生成）的 scripts/setup-test-db.mjs 在 env 缺省时
回退到 config-vars.yaml 的源库名并 DROP+CREATE——xlyClaude13 的源库
xlyweberp_vibe_erp_async 因此被清空重灌（2026-07-10 事故）。laneDbSupport 探测
只查 env 支持、且仅并行波次才跑，串行门裸跑脚本无任何拦截。

现 preflight 启动即 grep 目标项目 setup-test-db.mjs 是否含 COPY_SCHEMA
（新复制副本模型标识），不含即 halt 并给出用 skeleton-gen 模板升级的指引。

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

编码期测试的 DB 时序从「DROP+CREATE 空库 → Flyway 从零重建 → seed」
改为「mysqldump 复制源库→一次性副本 → Flyway 只 apply 本轮新迁移 →
跑测试 → 绿后晋升新迁移到源库 → 无论红绿删副本」。

- 新模板 scripts/drop-test-db.mjs（删副本，硬拒删源库）、
  scripts/promote-to-source.mjs（移植 flyway 历史行+重放迁移到源库；
  跨 lane 串行由编排层 testGate 起栈互斥保证，文件锁兜底同树重跑）
- setup-test-db：DROP 空库 → 复制源库到副本；test.mjs：try/finally
  删副本 + 绿后晋升 + 串行缺省显式导出副本名 <schema>__test
- 命名约定（5 脚本共享）：COPY = env > marker > <source>__test，
  每脚本 COPY===SOURCE 即拒绝；application*.yml 占位缺省改为副本名
- 新 lib/bootstrap-source-flyway.mjs：db-init 建源库+apply V1+写
  checksum 与 Flyway 一致的历史行（Plan 期无 app 可起，手算 CRC32）；
  db-init B 段三步换一次 bootstrap 调用
- coding.mjs 各闸时序对齐；globalTeardown 只 kill 不删副本（teardown
  删副本会让其后的 promote 查不到副本历史而静默跳过晋升）；行为门/
  seed 契约允许清单补 drop-test-db；前端 testGate 补收尾删副本
- 模板测试重写 + 新增 drop/promote/bootstrap 测试（133 全绿，全离线）

已知残留：bootstrap 手算 Flyway checksum 未真机验证（若不一致首次
起后端报 checksum mismatch，改 flywayChecksum 一处即可）；演示种子
固定主键区间 1000–9999 与源库真实自增数据增长存在长期碰撞风险。

前端段开头一次性 Playwright headless 渲染 prototype/**/*.html 本身：
截图归档为可视化基线 + 跑原型自带交互点击冒烟 + 捕获 JS/console 错误。
与行为门正交（Preview 测静态原型、Behavior 测实现）。硬门：渲染失败 /
脚本未捕获异常(jsErrors)→仲裁(只许 retry/halt)，halt 即停下等人工回
plan/add-req 修原型后重跑（coding 不改原型源码）；console.error advisory；
环境未就绪(Playwright/浏览器缺失)才 retry→仲裁降级；无 prototype/ 跳过。

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

让前端不依赖后端的工作与后端波次并发，所有真后端测试延后。5 类改动：
- tddPrompt/verifyPrompt 加 feStage：jsdom 模式只处理 jsdom 任务、只跑 vitest、
  硬禁 e2e 命令；e2e 模式只补延后的 e2e 任务。新增 fe-code-done/<FE> 中间 tag。
- featureLoop 加 feStage 分流：jsdom 跳 review 打 fe-code-done；e2e/all 走
  review→req-done。新增 runFrontendPhase1（前端 worktree，不调 phase()、不
  merge/milestone、永不 throw）。
- 主循环：frontendOverlap 开时把 frontend-phase 从波次图剔除、起 phase1 与后端
  波次并发；屏障后 reconcile（merge default→frontend-phase）+ 标准
  runModule(feStage=e2e) 主根全栈跑 phase2。后端未全 done / phase1 halt → phase2
  延后、产物保留 resume，绝不新增 halt 点。
- coding-start SKILL.md + README：开关说明，缺省不传（同 features 闸纪律）。

重叠期前端无栈/无固定端口/无 DB，补 8/9/10 不变量与端口/lane 安全全保住。
缺省关时 feStage 恒 all、新分支不激活、新编排整段跳过，现行行为零变化。
语法门通过。设计真值见 docs/superpowers/plans/2026-06-15-frontend-overlap-jsdom.md。

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

下文"派 Agent 子会话跑测试 / 主会话绝不直接跑测试"护栏的真实意图 =
测试执行与主推理流隔离、只回收结构化结果。本运行环境若无 Agent/Task 派发
工具，则以 Bash run_in_background 隔离后台子进程作为该子会话的物理实现
（输出重定向到 .tmp/ 日志，只读回 {command,exit_code,passed/failed} 摘要），
已满足护栏意图，故绝不因"缺派发工具"halt（非硬事实缺失、retry 不改变工具面）。
仍禁止在主推理流内联同步跑测试并把全文 stdout 读进上下文。

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

rule 1 翻转：docs/02 § 二 列出顺序只是排版次序、不构成依赖；order 边
仅在 docs/06（或 REQ 卡）显式声明"X 必先于 Y"时才加。明确堵死本次实测的
误读——对已完成模块的 fk/api 证据绝不构成两个待跑模块间的 order 理由
（scheduler 曾拿 PUR→BAC[fk] 当借口给 PUR←SAL 加链式 order 边）。两个待跑
模块间无 fk/api/seed/共享表/docs 显式约束 → 不加边、落同一波并行（默认而非例外）。

保守偏置同步收窄："不确定"仅指怀疑真实依赖却证据不全，绝不把"docs/02 里
靠后"当不确定理由——否则该"最高优先级"段会盖过 rule 1。

实测背景（xlyClaude13）：待跑 PUR/SAL/USR 表归属不相交、彼此无真实依赖，
旧提示却链式 order 串成 USR→SAL→PUR，每波仅 1 ready，maxWidth=3 形同虚设。
修复后三者应进同一波 3 路并行。

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

- 调度：scheduler 子代理只输出依赖边+证据（宁串勿并），JS 做完整性校验 + Kahn 拓扑波次；frontend-phase 由 JS 硬规则依赖全部后端
- 隔离：lane worktree（独立 index）+ lane 测试库（ERP_TEST_DB_SCHEMA）+ migration 版本段（maxV 全局并集）+ 起栈互斥锁（Seed/testGate）
- 执行：波次 parallel + milestone/RESUME 主根互斥 + halt 波次边界收敛 + 图状 pending(blockedBy)；runModule 永不 throw
- feature 级：spec 预生成（写盘不 commit、末端统一提交）+ 后端 REQ 批并行（准入闸=文件集两两不相交∧不改 schema，冲突即弃分支串行重跑）
- 穿线：模块作用域 prompt/runner 经 ctx(c) 取根，ROOT 仅主根专属操作；decisions 记账 per-module sink 取代全局水位线
- 降级原则：任何并行机制失败一律 fail-open 回串行，零新增 halt 点；parallel 缺省/modules:false 与原行为一行不差

- bestEffortAction(prompt, {label, phase, okMsg, failTag, errTag})：收敛 recordResume /
  ensureLedgerBaseline 逐行同构的 try/catch 包裹（失败/异常只 log 绝不阻断主流程；
  ≠ runAction：不经 adjudicate、绝不 halt）。日志文案与重构前逐字一致（errTag 区分
  失败/异常两条前缀），返回布尔供水位线判断。
- decisionDigestMd helper 消除决策摘要模板的字节级双份拷贝；flushedCount 水位线
  （仅 per-module flush 成功才推进）使 loop-end 条目只补「未被逐模块条目覆盖的增量」
  ——N 模块全绿不再每条决策在 RESUME.md 写两遍；flush 失败时 loop-end 兜底补记保留。
- add-req 步骤 0/1 合并为单次 scan（scan 输出本就同时含 ledgerExists 与
  new/changed/removed，重复扫描纯冗余）；删步骤 6 无操作性说明尾句。

- auto-continue.sh：sentinel 检测只认 transcript 的 assistant 行（修自匹配 bug——
  block reason 自带 [ERP-HALT] 字面量、下次 Stop 命中自己，钩子实际只能续跑一次）；
  窗口 60→200 行，兜住「横幅在前、诊断在后」的回合；删 4000B 字节增长启发式
  （与 PostToolUse 清零重复且方向性错误——纯文字空转一轮也超 4000B，上限永远到不了）；
  reason 文案去掉对已删 skill 链的指挥与 [ERP-HALT] 字面量。
- [ERP-HALT] 补全到全部刻意停下点（合计 12 处打印点）：add-req 4 处（前置拦截/
  基线停下/空增量/完成横幅）、coding-start 步骤 1/2、plan 阶段 5 处（plan-start
  终结闸 / downstream-gen A5 / db-design-gen 审阅 / scope-lock 骨架 / project-init
  安装失败）；coding-start :130 说明文字去字面量防误触发。
- StopFailure：官方语义为「输出与退出码被忽略、无 decision 控制」（无法在钩子层
  自动续跑；核实于 2026-06-11 code.claude.com/docs/en/hooks.md）。接线
  log-stop-failure.sh：记录中断时间与 error_type 到 $TMPDIR/erp-stopfailure.log，
  供人工/外部 watcher 据此续跑。
- coding.mjs preflight：起跑线按 docs/04 § 零探测 node/JDK/DB 客户端/测试入口，
  工具链缺失带安装/配置命令的诊断 halt——不再拖到 test-gate 才爆、白跑几十分钟编码。

任何 halt 的原因必须直达终端，而不是埋在 Workflow 返回值/RESUME.md/TypeError 里：

- haltError()：HALT 抛出前先 log（/workflows 进度叙述行可见）。启动期 4 处
  （invalid-projectRoot / assertSafeId / router-violation×2）换用；模块循环 catch 补
  「⛔ HALT — 模块 <id>：<原因>」；loop-end 补最终状态 log（halt 模块/原因/待跑清单）。
- agent() null 防御：断网/机器休眠时子代理返回 null，不再以 TypeError 形态 halt——
  adjudicate null→确定性默认 retry；runStage/runAction null→经仲裁重试（上限
  ADJUDICATE_MAX）；其余 32 处直调点换 agentR()（null→带 label 的诊断 halt）；
  flipDocs08Checkbox 保持裸 agent + null 容忍，守住其「绝不 halt」契约。
- coding-start 步骤 6：Workflow 通知返回后第一段输出必须是 halt/完成横幅
  （halt 原因全文不许截断或转述 + 已完成/pending 清单 + [ERP-HALT] 终止标记）。

P1#2 — validate-ddl 支持增量 migration：
- parseDDL 新增第三遍 mergeAlterStatements：ALTER TABLE ADD COLUMN /
  ADD [UNIQUE] INDEX|KEY / ADD PRIMARY KEY 并入对应表（仅追加式，
  MODIFY/CHANGE/DROP/RENAME 不处理；并集与文件顺序无关）。
- CLI 接受多个 DDL 文件：node validate-ddl docs/03 sql/migrations/V*.sql，
  CREATE + 各 V_n 的 ALTER ADD 并集 ↔ docs/03 累积 SSoT 做 4 维比对。
- add-req SKILL 新增「增量 DDL 校验(fail-closed)」闸门，替换原「多 migration 不适用」说明。
- 7 个新测试（含 DEFAULT 字面量里的 ALTER 文本不被误吃）；52/52 通过。

P1#3 — coding 首跑自动建需求台账基线：
- coding-start 透传 pluginRoot；coding.mjs ensureLedgerBaseline()
  首跑若 .req-ledger.json 缺失则 commit 基线（幂等、best-effort、缺 pluginRoot 静默跳过），
  使日后 /add-req 能识别增量、免空跑。

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

P0 — add-req 从不 git-commit 自己的产物，导致工作树脏、coding-start 起 coding.mjs
时撞「工作树必须干净」前置（HALT 或被误并进功能分支）：
- 步骤 0 基线：写 .req-ledger.json 后 git add+commit
- 步骤 6：把本次全部增量产物（docs/01/02/03/05/08 + sql/migrations/V_n + .req-ledger.json）
  在当前(默认)分支统一 git commit，并用 status --porcelain 复核工作树干净

P1#1 — RESUME.md 原先只在主循环末尾写，硬中断(进程被杀)到不了写入点 → 本次运行零 handoff：
- 每个模块 runMilestone 落定后即 best-effort 追加一条「✅ 模块完成」(含本模块自主决策摘要)，
  按 decStart 水位线切出本模块决策；使硬中断也能复盘已完成到哪、各模块做过哪些假设
- loop-end 的 halt / 全完成汇总条目保留(halt 原因是 per-milestone 无法捕获的)

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

中断/halt 后重跑能复盘上次状态，不只恢复进度。编码阶段保持全自动静默不变。

- coding.mjs：新增 resumeJournalPromptM + recordResume（best-effort，写失败绝不阻断/
  掩盖主流程）。主循环结束（halt 或全完成）时向 docs/superpowers/RESUME.md 追加一条：
  halt 原因 + 本次自主默认假设(decisions 摘要) + 待跑模块 + 下一步
- coding-start：新增步骤 3.5，重跑时读 RESUME.md 末尾条目向用户复盘上次 halt/完成状态
- 进度真值仍是 git tag（milestone/req-done）+ committed 工件——硬中断后 Router 据此续跑；
  RESUME.md 补的是跨会话会丢失的「为何停/做过哪些假设」定向信息（GSD continue-here.md 类比）
- 硬中断(进程被杀)到不了写入点：那种情况无 halt 原因可记，且 tag+工件已够续跑，无信息损失

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

标准列：每表 7 列（新增 iOrder/sMemo；sId/sBrandsId/sSubsidiaryId 改 varchar(50) NOT NULL），从表额外 +sParentId 共 8 列。docs-03 模板 + A3 渲染规则 + A4 DDL 默认值翻译（CURRENT_TIMESTAMP / DEFAULT '1111111111' / iOrder app-assigned）。

去外键：A3 不再推导 FK 约束（改语义引用关系，无 ON DELETE/ON UPDATE，应用层维护一致性）；A4 DDL 不生成 ALTER ADD FOREIGN KEY；validate-ddl 移除外键维度 5→4 维（表/列/类型/索引），单测 45 pass/0 fail；coding.mjs 种子/sentinel「FK 有序」→「按语义引用有序」（保留先被引用方后引用方/不可悬空）。

注：db-design-gen 的 docs/06 读取清单/步骤B 两条 bullet 与本区域改动同处一个 diff hunk，随本提交落入（实属 docs/06 feature 的 A3 接入）。

- A2 skeleton-gen 末尾新增 step F：创建空白 docs/06-实现策略.md，QA 闸循环至用户确认填完才进 A3（原 F 进入 A3 顺延为 G）
- A3 db-design-gen 读取清单 + 步骤B + 参考接入 docs/06
- A5 downstream-gen docs/02 构建顺序 / docs/05 端点 + 参考接入 docs/06
- coding.mjs deriveSpecPrompt（前端+后端）把 docs/06 作为 spec 收集上下文

- 子模块代码：大写短码(USR/ROLE) → 大驼峰英文名、不限长度(UserInfo/Role)
- 功能名：英文大写 [A-Z0-9_]/下划线(PWD_RESET) → 大驼峰 [A-Za-z0-9]/直接拼接(PwdReset)
- 模块代码不变(大写短码 USR)；结构仍 <模块代码>-<子模块代码>-<功能名> 恒 3 段
- 规范示例统一 USR-USR-LOGIN → USR-UserInfo-Login；docs-01 五列示例行同步
- 同步 7 文件：README/coding.mjs/scope-lock/docs-01/CLAUDE/plan-start/docs-04

- index 模板：三列 → 五列（模块代码/模块名称/子模块代码/子模块名称/核心功能点），一行一个子模块
- 卡片文件名：REQ-XXX-NNN.md → <req_id>.md，req_id 恒 3 段（如 USR-USR-LOGIN），功能名由 CC 据核心功能点推断（英文大写、[A-Z0-9_]、多词下划线、子模块内唯一），保持文件名==req_id 不变量
- scope-lock：五列解析 + 按模块代码聚合建目录 + req_id 生成规则；E.1 glob 改 */*.md 跳过 _module.md
- db-design-gen/downstream-gen：REQ-*.md glob 同步；docs/05 结构检查锚点 ### REQ- → 三级标题端点段
- CLAUDE/docs-04 模板 commit 后缀、plan-start 示例、coding.mjs 提示词文案（238/1322）、README 同步
- docs-08 checkbox 文本与 scope-lock Edit 锚点逐字节同步；流程/闸门/tag 机制零改动

行为门 v3（docs/design/2026-06-05-frontend-behavior-stage-gate.md）：
- 行为验收从 per-FE review approve 子门迁回阶段末尾一次（phase Behavior，
  featureLoop 后、testGate 前），保留 fix 循环（BEHAVIOR_STAGE_MAX=3 轮，
  fix 后全量前端单测复验再重跑门）
- req-done/<FE> 语义降为「仅静态 review 过」；行为绿改由 reportPrompt 校验
  阶段级证据（module-reports/frontend-phase-behavior-r*-a*.md 最后一份非 RED）
- build-failed 取消「兄弟未实现」短路（阶段末尾全 FE 已实现）；断言作用域 =
  全部 FE spec「行为验收作用域」小节并集，缺小节记 scope-missing 阻断 green
- 新增样式层 styleIssues（颜色 token 比对 + layout sanity 共 6 kind），
  降维并入 behaviorHard 与交互硬问题同口径 fix；环境仲裁透传 riders 计数

前端测试目录隔离（对齐后端 src/main↔src/test 物理分离）：
- 锁定约定：单测 frontend/tests/** 镜像 src/（smoke 归 tests/__smoke__/ 且
  以 .test.* 结尾），e2e 在 frontend/e2e/，frontend/src/ 禁任何测试产物；
  vitest include 统一限定 tests/**/*.test.*
- 五层防线：docs-04 模板 §2.1 锁定约定 / planPrompt+tddPrompt 硬护栏 /
  fe-skeleton 单测基线 / code-reviewer 新增第 8 维「测试文件隔离」
- legacy 守卫：frontend/src/ 内已存在 colocated 测试时绝不收窄 include
  （防旧单测静默停跑），骨架幂等检测同步豁免，留人工迁移

经两轮多代理对抗审计（34 agents），确认项均已修复。

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

- coding.mjs: per-module Seed stage after backend testGate (generate
  sql/seed/NN__<module>.sql, cold-stack verify with PK-range COUNT
  reconciliation); behavior gate step2 -> 5-step ordering (demo seed
  before sentinel, sentinel fixed >=100000 range); fe-skeleton adds
  Playwright globalSetup e2e baseline (seed + admin storageState);
  fe tdd e2e assertion constraints
- skeleton-gen: new scripts-seed-demo-data-template.mjs (mysql CLI,
  _demo_seed_history idempotency ledger, offline-validatable, atomic
  apply+ledger batch) + lib offline tests (93/93 green)
- db-init: B.3 re-clean DB after DDL smoke apply (hand schema back to
  Flyway, avoid missing-history-table error); fix step-D typo
- docs-04/CLAUDE templates: data baseline & demo-seed conventions
  (PK ranges 1-999 init / 1000-9999 seed / >=100000 sentinel)

…rd, coverage reconciliation, testdb halt)

Post-implementation multi-agent review (6 dims + per-finding adversarial verify) found the control-flow sound and the goal mostly-achieved; this lands the three deterministic, low-risk fixes among the confirmed findings.

- build-failed short-circuit (must-fix): behaviorSubGate now validates the LLM's classification before green-by-skip — requires non-empty rootCausePath AND no interaction/sentinel hard issues riding along; a "dirty" build-failed goes through adjudicate(allowContinue:false) retry/halt instead of silently approving. The skeleton (lazy router + FeStub) makes legit sibling-unimpl build breaks rare, so a build-failed is more likely a real in-FE shared-code regression — the boundary comment §107-108 claimed load-bearing but had zero JS enforcement.

- coverage reconciliation backstop (§3.6): empty-coverage only guarded ==0; now 0<routesReached<routesPlanned with the shortfall unexplained by route-level coverageGaps -> adjudicate(allowContinue:false). Closes the partial-coverage false-green. Counts route-level reasons only; over-counting can only suppress the gate, never false-halt.

- test-DB guard direct-halt now implemented: TESTDB_GUARD_MARK in envError.detail + behaviorTestDbGuardTripped -> immediate HALT on the first result, honoring step2's "no retry, no adjudication" promise (previously prompt-only; a guard trip wrongly entered the generic stack-not-ready retry path, ~5 redundant setup-test-db.mjs runs).

Left as accepted design trade-offs (documented in design §12): self-attested whitelist/route scope, soft-by-source non-data text, disabled-control should-work recovery limited to submit buttons.

Verified: SYNTAX_OK (wrapped check), 87/87 lib tests pass, no time/random builtins. v2 design doc updated (§3/5/6.2/6.3 + new §12).

Replaces the phase-level read-only behavior-gate with a per-FE acceptance dimension: each FE is approved only when the code-reviewer approves AND runtime behavior verification is green. Behavior defects (dead control / sentinel text mismatch) become fixable must-fix that drive verify->fix->re-verify, not halts.

- reviewWithFixLoop (frontend only, via if(fe)): at the approve gate, behaviorSubGate boots this FE's full stack + seeds sentinels, enumerates this FE's routes, two-tier asserts. Hard issues with a locator -> fixPrompt -> functional reverify -> next behaviorRound; soft text (i18n/literal/semantic) -> adjudicate(continue); behaviorRound bounded by BEHAVIOR_FE_MAX=3, env race by BEHAVIOR_ATTEMPT_MAX=2. Backend featureLoop branch unchanged.

- New runFrontendSkeleton stage (before featureLoop(frontend)): App shell + full lazy router + FeStub placeholders + shared nav, so the app is buildable at every mid-phase point; tdd swaps FeStub->real component per FE. Idempotent via fe-skeleton-done tag.

- BEHAVIOR_GATE_SCHEMA gains build-failed envError kind (sibling-FE-unimpl short-circuit, not a bug) + locator-not-resolvable coverage reason; deriveSpec emits a per-FE route-scope section, reviewer validates it.

- Removed phase-level runBehaviorGate + 'Behavior' phase; kept phase-level testGate (regression). REVIEW_HARD_ROUNDS 8->10.

- Safety: test-DB naming guard pushed into scripts-setup-test-db.mjs template (fail-closed unless name contains test/_dev/_local or ALLOW_NONTEST_DROP=1) + 3 tests.

- agentType stays erp-workflow:code-reviewer. v1 design doc marked SUPERSEDED; v2 design at docs/design/2026-06-02-frontend-behavior-in-review-loop.md.

Verified: wrapped syntax check SYNTAX_OK, 87/87 lib tests pass, no orphan refs, no time/random builtins, top-level return intact. Not yet run end-to-end against a real ERP project.

New 'Behavior' stage between Gate and Milestone, frontend-phase only, after testGate green and before report/milestone. Verifies every interactive control actually works and every text region shows the right content, independent of the tests the tdd agent wrote.

- BEHAVIOR_GATE_SCHEMA / behaviorGateContract() / behaviorGatePrompt() / runBehaviorGate(); reportPrompt now gates the milestone on behavior-gate evidence (frontend-phase-behavior-gate-r*.md, last attempt must be non-RED).

- Two-tier failure: interaction defects (incl. binding-garbage) flake-retry once then hard-halt via adjudicate(allowContinue:false); text issues split by source (sentinel=objective -> no continue; i18n/literal/semantic=adjudicable). Convergence loop re-runs the env + interaction hard gates after any text-layer retry so a refreshed result can't slip a green past the hard gates.

- Full-stack seeded run: test-DB name guard (deterministic halt, not adjudicated), strict 4-phase ordering (empty DB -> boot backend so Flyway builds schema -> seed -> boot frontend), auth bootstrap via storageState, router-config-driven route discovery, ephemeral .tmp/behavior-gate runner with finally teardown, type-legal per-field-unique sentinels.

- agentType uses the plugin-namespaced 'erp-workflow:code-reviewer' (a bare 'code-reviewer' is ambiguous with feature-dev:code-reviewer); README + agents/code-reviewer.md aligned (frontmatter name: stays bare).

- Design: docs/design/2026-06-02-frontend-behavior-gate.md. README + coding-start banner updated.

缺值类(A)改为 stage 自主决策继续并登记 decisions[]；结构违约/重试耗尽(B/C)经新增 adjudicate() 仲裁
retry/continue/halt（runStage/runAction 包装，ADJUDICATE_MAX=3）；dirty 工作树自主恢复（带分支护栏，
非功能分支/越界改动仍 halt）。review 软5/硬8 轮；docs/08 checkbox 降级为纯可视化（req-done tag 为真值）。

硬边界保持: merge 冲突 / invalid-projectRoot / assertSafeId 注入护栏 / 红色测试绝不 continue 跳过
（verify/reverify/tdd/report allowContinue:false）。JS HALT throw 37->26。

- docs-04 template: remove § 2.5 样式与主题 (tokens live in src/styles/tokens.css) + § 3.5 配置与安全 (config in config-vars.yaml, rules in docs/07→now config-vars header)
- styles-tokens-template.css: fix 3 stale docs/06 refs missed in the earlier docs/06 removal (greps had excluded *.css) → self-contained '色值单一来源 / SSoT'
- coding.mjs: frontend ref §一 前端架构 → §二 前端规范 (§一 is 后端); backend drop frontend §2.1 → §1.2 分层; 样式/色值 → tokens.css; remove docs/07 from value-lookup order

- delete docs-09-structure-template.md (its § 二/§ 三 dir layout duplicated docs/04 § 1.2/2.1; § 四 docs-tree was a self-referential maintenance trap; § 五 overlapped docs/04)
- skeleton-gen B.1 now generates only docs/07; B.2 captures backend/frontend dir layout into docs/04 § 1.2/2.1; frontmatter/checkbox/参考 drop docs/09
- coding.mjs (6 refs): file placement -> docs/04 § 1.2/2.1; frontend root -> frontend/ convention; cross-module path->module -> docs/08 § 二 路径: field
- CLAUDE-template rule #2 -> docs/04 § 1.2/2.1; docs-08 checkbox + README A2/template-table drop docs/09

- C.1: stop generating sql/migrations/.gitkeep (A4 db-init's Write V1 creates the dir); README A2 drops 'create empty migrations dir'
- precedence rule: on color conflict, tokens.css wins over prototype (prototype = structure/layout/interaction; tokens.css = color) — encoded in skeleton-gen note, coding.mjs frontend stage, code-reviewer § Design Tokens