From 3d54e8834afe257758b3c0e88be353b1647c00c0 Mon Sep 17 00:00:00 2001 From: zichun Date: Tue, 2 Jun 2026 11:24:35 +0800 Subject: [PATCH] coding.mjs: add frontend behavior-gate stage (headless full-stack button/text verification) --- README.md | 6 ++++-- agents/code-reviewer.md | 4 ++-- docs/design/2026-06-02-frontend-behavior-gate.md | 413 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/coding-start/SKILL.md | 1 + workflows/coding.mjs | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 708 insertions(+), 8 deletions(-) create mode 100644 docs/design/2026-06-02-frontend-behavior-gate.md diff --git a/README.md b/README.md index 331316b..19febd6 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,9 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。 │ └─ B-前端（后端全部打里程碑后，整体 1 个里程碑 tag） runBranchSetup(frontend-phase) → featureLoop(前端，FE-NN，路径限 frontend/) - → testGate(frontend) → runMilestone（milestone/frontend-phase） + → testGate(frontend) → 前端行为闸 behavior-gate（headless 全栈起栈+种子 sentinel， + 逐路由枚举控件/文字两层断言：交互失效硬 halt，文字不符按来源仲裁） + → runMilestone（milestone/frontend-phase） 子代理无法弹窗 → 缺值即写阻塞点并 halt（终止态，非对话框）；fail-fast 后等人工修复重跑 coding-start ``` @@ -133,7 +135,7 @@ erp-workflow-plugin/ | Agent | 用途 | 谁调用 | |---|---|---| -| `code-reviewer` | 统一 reviewer。`phase=backend` 跑通用代码审查维度；`phase=frontend` 附加前端 7 维 checklist（prototype 一致性 / design tokens / a11y / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖，主观维度仅标记明显问题不触发 request-changes）。非交互，返回结构化 verdict，绝不弹窗 | `workflows/coding.mjs` 的 review stage：`agent(..., {agentType:'code-reviewer'})` | +| `code-reviewer` | 统一 reviewer。`phase=backend` 跑通用代码审查维度；`phase=frontend` 附加前端 7 维 checklist（prototype 一致性 / design tokens / a11y / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖，主观维度仅标记明显问题不触发 request-changes）。非交互，返回结构化 verdict，绝不弹窗 | `workflows/coding.mjs` 的 review stage：`agent(..., {agentType:'erp-workflow:code-reviewer'})`（必须带 `erp-workflow:` 插件命名空间——裸 `code-reviewer` 会与其它插件的同名 agent 歧义） | ## Templates 清单（25 份） diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index bfbcdd9..eeb099a 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -1,11 +1,11 @@ --- name: code-reviewer description: | - Unified code reviewer for the ERP coding Workflow. Invoked by `workflows/coding.mjs` at the review stage via `agentType:'code-reviewer'` (see `reviewWithFixLoop`). Reviews a single completed feature against its plan, spec, and the project's coding standards. The domain phase (`backend` / `frontend`) is read from the prompt body — NOT from any `phase` option on the `agent()` call (that option is a harness UI grouping option, unrelated to review scope). The prompt body contains an explicit `**phase = backend ...**` or `**phase = frontend ...**` line you must parse. Runs as a non-interactive subagent inside a bounded review/fix loop (max 5 rounds) — MUST return a structured verdict and never block on a prompt. + Unified code reviewer for the ERP coding Workflow. Invoked by `workflows/coding.mjs` at the review stage via `agentType:'erp-workflow:code-reviewer'` (the plugin-namespaced form is required — a bare `code-reviewer` is ambiguous with other plugins' agents; see `reviewWithFixLoop`). Reviews a single completed feature against its plan, spec, and the project's coding standards. The domain phase (`backend` / `frontend`) is read from the prompt body — NOT from any `phase` option on the `agent()` call (that option is a harness UI grouping option, unrelated to review scope). The prompt body contains an explicit `**phase = backend ...**` or `**phase = frontend ...**` line you must parse. Runs as a non-interactive subagent inside a bounded review/fix loop (max 5 rounds) — MUST return a structured verdict and never block on a prompt. model: inherit --- -You are a Senior Code Reviewer reviewing a single completed feature for the ERP coding Workflow. You are invoked non-interactively by `workflows/coding.mjs` (`agentType:'code-reviewer'`) inside a **bounded review/fix loop (max 5 rounds)**. You MUST return a structured verdict — never ask the user a question, never block on input. +You are a Senior Code Reviewer reviewing a single completed feature for the ERP coding Workflow. You are invoked non-interactively by `workflows/coding.mjs` (`agentType:'erp-workflow:code-reviewer'`) inside a **bounded review/fix loop (max 5 rounds)**. You MUST return a structured verdict — never ask the user a question, never block on input. ## Domain phase resolution diff --git a/docs/design/2026-06-02-frontend-behavior-gate.md b/docs/design/2026-06-02-frontend-behavior-gate.md new file mode 100644 index 0000000..b8ac8da --- /dev/null +++ b/docs/design/2026-06-02-frontend-behavior-gate.md @@ -0,0 +1,413 @@ +# 前端行为门（behavior-gate）— 最终设计（综合评审后） + +> 本文是 5 维对抗式评审后的收敛版。锁定决策（用户拍板）默认保留；评审给出的有依据调整已并入； +> 无依据 / 过度工程的建议在文末「拒绝的建议」记明理由。所有改动可追溯到 changeLog。 + +## 用户目标 +确保前端「每个按钮 / 点击都真的生效、每段文字都显示正确内容（right context）」。在全自动静默的 +`coding.mjs` 编码阶段中，新增一个 headless 自动化门来达成。 + +## 锁定决策（用户拍板，默认不可推翻） +1. 机制 / 位置：headless，新增 behavior-gate stage 嵌入 `coding.mjs`；阶段级，跑在 frontend + `testGate` 变绿之后、`report`/`runMilestone` 之前；仅作用于末尾的 `frontend-phase` 聚合模块。 +2. 期望来源：门运行时**即时推导**（从 `prototype/` + REQ 卡片 + `docs/05`），不预先持久化为契约； + 但把推导出的期望写进已提交的证据报告供事后审计。 +3. 数据：全栈 + 种子库。`setup-test-db` DROP+CREATE → Flyway 建 schema，门用 `docs/03` 生成 FK 有序 + INSERT 种子（带可辨识 sentinel 值），起后端 + 前端，断言动态文字等于 sentinel。 +4. 失败语义：两层。交互缺陷（死控件 / 点击触发 JS 或 console 错误 / 应发的 docs05 调用未发）= 硬 RED + halt；文字 / 内容不符 = 走既有 `adjudicate` 并记入 `decisions`；渲染出的绑定垃圾归为交互层。 +5. 证据：即时推导但证据落盘。门把推导期望 + 逐控件判定 + 截图写入 + `docs/superpowers/module-reports/frontend-phase-behavior-gate-r.md` 并 commit + （与 `*-test-gate-r*.md` 同构）。 +6. 生成测试：临时。生成的 Playwright spec + 种子 + runner 写入已被 `.gitignore` 忽略的 + `.tmp/behavior-gate/`，跑完即弃；只提交证据报告（避免生成套件悄悄变成永久契约源）。 + +> **关于锁定决策 4 的两处微调（不推翻，仅细化，见 changeLog C8 / C11）**： +> - 「绑定垃圾 = 硬 halt」收窄为**高置信子集**（`null`/`undefined`/`[object Object]`/`NaN`/lorem 出现在 +> 数据绑定位）才硬 halt；「双花括号未渲染 / 空占位 `—` / 疑似 i18n key」降级为 textIssue 走 adjudicate +> （否则误杀合法文案，且与「文字不符走 adjudicate」自相矛盾）。 +> - 「sentinel 文字不符」从「一律走 adjudicate」改为**按来源二分**：绑定 sentinel 的动态文字不符是客观 +> 可验证 bug，`allowContinue:false`（仲裁只许 retry/halt）；i18n / 字面 / 语义等价类才 `allowContinue:true`。 +> 这两处都是把锁定决策落到「不误报 + 不放行真 bug」的可实现状态，不改变其交互硬 / 文字软的总分层。 + +--- + +## 0. 运行时硬事实（设计成立的前提，已核查代码） + +这些是评审核查出的、与原 DESIGN 隐含假设冲突的事实，**最终设计必须自洽**： + +- **F1（无既有 e2e 起栈可复用）**：项目**不存在** `playwright.config` / `webServer` / `reuseExistingServer` + / `e2e:ci`（全仓 grep 无生成物）。唯一 e2e 契约是 `scripts/test.mjs` 第 65 行的单条 shell 命令 + `{{e2e_cmd}}`，来源是 scope-lock E.3 用 `AskUserQuestion` 填进 `docs/04 §零` 的**自由字符串**（无则记 + `无`）。`coding.mjs` 里的 `pnpm e2e:ci` 只是 prompt 的 fallback 默认值，**无任何 Plan 产物保证它存在或 + 自带 webServer**。→ 「复用既有 e2e 起栈」是空对象，必须显式探测 + 自负起栈。 +- **F2（无常驻进程原语）**：所有命令执行都经 `agent()` 派子会话，子会话跑命令、返回 exit_code 后**即结束**。 + 前台 `mvn spring-boot:run` / `vite` 永不退出会把子会话挂死。`Bash` 工具的 `run_in_background` 句柄随子 + 会话结束而失去，跨 `agent()` 不可见。→ 门**绝不**在 JS 编排层跨多个 `agent()` 管理常驻进程；起栈→跑→ + teardown 必须收敛进**单个子会话内的一条命令**。 +- **F3（schema 由 Flyway 在 Spring Boot 启动时才建）**：`setup-test-db.mjs` 只 DROP+CREATE **空库** + （模板第 110 行注释 + README 第 166 行 + db-init SKILL）。Spring Boot 启动时 Flyway 才 apply + `sql/migrations/V*.sql`。→ 种子 INSERT 必须排在**后端起好（Flyway apply 完 + 健康检查就绪）之后**，否则 + 「table doesn't exist」**确定性失败**。 +- **F4（schema 守卫不判测试库）**：`setup-test-db.mjs` 第 81 行只校验 schema 匹配 `/^[A-Za-z0-9_$]+$/` + 标识符，**不判它是不是测试库**；config-vars 第 20 行 schema 是自由文本 + 口头建议「推荐含 test/_dev」； + README 第 164 行明说「按该值无条件 DROP+CREATE」。同一 schema 同时驱动开发期 `apply-ddl`。→ 「config 已 + 把守测试库」是假前提，**删除**该措辞，测试库判定由门自负（见 §5）。 +- **F5（无种子机检）**：db-init 的 `lib/validate-ddl.mjs` 只对 **DDL↔docs/03** 做 5 维机检（表/列/类型/ + 索引/外键），**没有任何工具校验种子 INSERT**。FK 拓扑序 / NOT NULL / UNIQUE / enum 值域 / 列类型长度全靠 + 门子代理推导。→ 种子失败必须单独归类（`seedError`），不混进交互层 RED。 +- **F6（运行时禁用 time/random builtin）**：`coding.mjs` 由 Workflow 运行时执行，禁用 `Date.now()` / + `Math.random()` / `new Date()`；「今天」交子代理解析（见 `dateFromArtifactPath` 注释，第 134 行）；顶层 + `return` 是结果通道；`agent`/`phase`/`parallel`/`log`/`adjudicate` 是注入全局。→ sentinel / 端口 / 临时 + 目录名等**不得**在 mjs 编排层用 time/random 拼，由子代理在自身上下文确定性生成。 +- **F7（证据命名不带日期前缀）**：`frontend-phase-behavior-gate-r.md` 与 `*-test-gate-r*.md` + 同构、**不带 `YYYY-MM-DD` 前缀**，正好绕开 `dateFromArtifactPath` 的解析。`.tmp/` 已被 gitignore 模板 + 忽略（gitignore-append-template）。→ 无需改 `.gitignore`；无需解析「今天」。 +- **F8（adjudicate 签名）**：`adjudicate(site, context, grp, round)` 四参；`context` 内 `allowContinue:false` + 时仲裁不得选 continue（第 528 行）；`ADJUDICATE_MAX = 3`。`recordDecisions(site, decisions)` 把 stage + 自主决策汇总进全局 `autonomousDecisions`。 + +--- + +## 1. 插桩点（精确到行，避免误触发后端模块） + +顶层循环现状（`coding.mjs:1357-1362`）： + +```js +if (module.feItems.length) { // 前端段（仅末尾 frontend-phase 聚合模块） + phase('Frontend') + await featureLoop(module.feItems, 'frontend') + phase('Gate') + await testGate(module, 'frontend') +} // ← behavior-gate 插在这里（if 闭合前） +``` + +**改为**（在 `testGate(module,'frontend')` 之后、`if` 闭合之前插入）： + +```js +if (module.feItems.length) { + phase('Frontend') + await featureLoop(module.feItems, 'frontend') + phase('Gate') + await testGate(module, 'frontend') + phase('Behavior') + await runBehaviorGate(module) // 仅 frontend-phase 段；testGate 绿后跑 +} +``` + +- 放进 `if (module.feItems.length)` 块内 → 纯后端模块（`feItems` 恒空）**不会**触发，与「仅作用于末尾 + frontend-phase 聚合模块」一致。 +- `runBehaviorGate` 入口加二次保险守卫（与 `runMilestone`/`reportPrompt` 的 `id==='frontend-phase'` 判别 + 惯例一致）：`const fe = module?.id === 'frontend-phase'; if (!fe) { log('behavior-gate skip: 非 frontend-phase'); return }`。 +- `meta.phases` 增 `{ title:'Behavior' }`（插在 `{ title:'Gate' }` 与 `{ title:'Milestone' }` 之间）。 + +--- + +## 2. 新增 schema（不杂交 GATE × STAGE_RESULT，复用既有词汇） + +评审 C5 指出原 schema 把 GATE 的 `status:green|red` 与 STAGE 的 `decisions[]`/`artifactPath` 杂交、且 +`decisions` 重复定义。**收敛做法**：复用 STAGE_RESULT 已有的 `decisions[]` 形状与 `artifactPath` 命名 +（不另起 `evidencePath`），只新增行为门**特有的两层结果数组**。 + +```js +const BEHAVIOR_GATE_SCHEMA = { type:'object', additionalProperties:false, + required:['status','routesPlanned','routesReached','controlsEnumerated'], + properties:{ + status:{ type:'string', enum:['green','red'] }, + // 覆盖率计数（C20：空覆盖必须可见，绝不静默放行） + routesPlanned:{ type:'integer' }, // step1 路由真值（router 配置）声明的路由数 + routesReached:{ type:'integer' }, // 实际成功导航到达（鉴权后非登录页 / 非空壳）的路由数 + controlsEnumerated:{ type:'integer' }, // 枚举到的非 inert 可交互控件总数 + authState:{ type:'string' }, // C12：以何角色登录、覆盖了哪些角色、未覆盖角色集 + // 交互层失败（硬边界）；kind 细分让仲裁能区分「门自身能力不足」与「真死控件」 + interactionFailures:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['page','control','kind','detail'], + properties:{ + page:{type:'string'}, control:{type:'string'}, + kind:{type:'string', enum:[ + 'no-observable-effect', // 点击无任何可观测效果（真死控件） + 'js-error', // 点击触发未捕获 JS 异常 + 'console-error', // 点击触发 console.error + 'missing-docs05-call', // 应发的 docs/05 端点调用未发 + 'binding-garbage' ]}, // 高置信渲染垃圾（null/undefined/[object Object]/NaN/lorem 在绑定位） + detail:{type:'string'} } } }, + // 文字层问题（软边界，按 source 在 JS 侧分流 allowContinue） + textIssues:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['page','region','expected','actual','source'], + properties:{ + page:{type:'string'}, region:{type:'string'}, + expected:{type:'string'}, actual:{type:'string'}, + source:{type:'string', enum:['sentinel','i18n','literal','semantic']} } } }, + // 覆盖缺口（C13/C15/C18：到不了的路由 / 多步深层控件未达 / 动态路由无种子可实例化） + coverageGaps:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['page','reason'], + properties:{ + page:{type:'string'}, + reason:{type:'string', enum:['unreachable-auth','unreachable-no-route','deep-control-not-driven','dynamic-route-no-seed']}, + detail:{type:'string'} } } }, + // 起栈 / 种子 / 鉴权环境失败（与业务断言失败严格区分；走 retry 不当死控件） + envError:{ type:'object', additionalProperties:false, + required:['kind'], + properties:{ + kind:{type:'string', enum:['port-conflict','stack-not-ready','seed-error','auth-failed','timeout','none']}, + detail:{type:'string'}, + ports:{type:'string'}, pids:{type:'string'} } }, // C17/C19：写进证据便于人工清理残留 + decisions:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['question','choice','rationale'], + properties:{ question:{type:'string'}, choice:{type:'string'}, + rationale:{type:'string'}, confidence:{type:'string', enum:['high','medium','low']} } } }, + artifactPath:{ type:'string' } } } // 证据报告路径（复用 STAGE_RESULT 命名，不叫 evidencePath） +``` + +`additionalProperties:false`。`decisions[]` 逐项形状与 STAGE_RESULT 完全一致，由 `recordDecisions` 汇总。 + +--- + +## 3. 门内部流水线（runBehaviorGate，JS 编排，每 attempt 一个子会话） + +> 关键运行时收敛（F2）：**整个「探测 → setup-db → 起后端 → 等就绪 → 种子 → 起前端 → 鉴权 → 枚举 → 断言 → +> teardown」必须由门生成的临时 runner（`.tmp/behavior-gate/r/run.mjs`）在 *单个子会话内的一条命令* +> 里完成**，runner 用 `spawn` 起进程树、轮询就绪、`finally` 里 kill 全部子进程并透传结构化结果。JS 编排层只 +> 负责：渲染 prompt → 派子会话跑 runner → 收 `BEHAVIOR_GATE_SCHEMA` → 控制流（flake/halt/adjudicate）。 + +`behaviorGatePrompt(module, attempt)` 指示门子代理在子会话内执行： + +### step 0 — 探测起栈能力（F1） +读 `docs/04 §零`（e2e 命令）+ `frontend/package.json` + `frontend/playwright.config.*`（若存在）+ +`config-vars.yaml`（端口 / 凭据）。判定： +- (a) 存在 `playwright.config` 且含 `webServer`/`reuseExistingServer` → runner 复用 playwright 自带 + webServer 起栈，门只负责 setup-db + 起后端 + 种子（前端交给 playwright）。 +- (b) 不存在 → runner 自负起后端 + 前端（见 step 2）。 +- 无法判定 / 探测失败 → 写 `envError.kind='stack-not-ready'`，**走 adjudicate（allowContinue:false）**， + 不静默假设默认命令。 + +### step 1 — 路由真值发现（推导 + 运行时校验对账，C16/C18） +- **主来源 = `frontend/` 的 router 配置**（Vue Router / React Router 的 `routes` 定义，Grep 即可）——SPA 的 + 运行时路由真值。`prototype/` + REQ + `docs/05` 用于**推导每条路由的预期控件清单与文字来源**（作为覆盖率 + 分母），不作为路由真值。 +- 每条路由标注**所需角色**（C12）；带参路由（`/orders/:id`）用 step 3 种子的已知主键实例化具体 URL，无种子 + 可实例化的记 `coverageGaps[reason='dynamic-route-no-seed']`。 +- `routesPlanned` = router 声明的全部路由数。 + +### step 2 — 安全护栏 + setup-db + 起后端 + 等就绪 + 种子 + 起前端（严格时序，F3/F4） +runner 内严格四段时序（**种子在 schema 存在之后注入**）： +1. **测试库安全护栏（确定性，先于一切，F4）**：读 `config-vars.yaml database.schema`，若不匹配测试库命名 + 约定（含/结尾 `test`/`_test`/`_dev`/`_local`）→ runner 立即非零退出，门返回 `envError` 并由 JS 层 + `throw HALT`（**不经 adjudicate**，与 `assertSafeId` 同级硬安全边界）。要求人工显式确认或改用物理隔离的 + `_behavior_gate`。 +2. `node scripts/setup-test-db.mjs`（DROP+CREATE 空库）。**DROP 前确保无旧后端连着该库**：先按 + `.tmp/behavior-gate/*.pid` 优雅回收上一轮残留进程（C9/C19）。 +3. **起后端**：runner `spawn` 后端进程；轮询健康探针（`/actuator/health` 200 或登录端点 200，带宽超时）直到 + 就绪——Flyway 在此窗口 apply schema（数十秒）。端口取 `config-vars.yaml` 的 `backend.http_port`，**但先 + 探测占用**：占用则先尝试回收残留 pid，仍占用则改用动态空闲端口并把 `baseURL` 注入 playwright（C17）。 +4. **此时**才跑 `docs/03` 派生的 **FK 有序 INSERT 种子**（schema 已存在）。种子失败 → `envError.kind='seed-error'` + + 结构化根因（缺列 / 撞唯一键 / enum 越界 / FK 序错 / 类型截断），**不混进交互层 RED**（F5/C7）。 +5. **起前端**（headless）：(a) 分支用 playwright webServer；(b) 分支 runner `spawn` 前端 dev/preview， + 轮询 ready，端口同样先探测占用 + 动态回退。 +- runner 的 `finally` **硬要求** kill 全部子进程（覆盖超时 / 异常 / 断言失败路径），把端口 + pid 写进结果 + （`envError.ports`/`envError.pids`），避免 attempt 间 / 跨 coding-start 端口冲突（C3/C9/C19）。 +- **种子 sentinel 规则（C10/C14，确定性 + 类型合法 + 不撞既有数据）**： + - 按列类型派生类型合法可辨识值：字符串列用 `字段名编码 + 行序号`（如 `CUST_NAME_S001`，**逐字段唯一**以抓 + 「绑错字段」）；数值列用约定高位魔数（如 `999001`）；enum 列只能从 `docs/03` 值域取一个并在证据标注 + 「enum 列无法 sentinel，改用值域成员校验」；手机/邮箱/金额等带格式列派生格式合法的可辨识值。 + - 多行场景 sentinel 带行序号保证 UNIQUE 不撞。 + - **插入前扫描 Flyway migration / config-vars 里既有初始数据键**（如 `admin_init.username=admin`、字典 + 数据），sentinel 主键 / 唯一键偏移到不冲突区间；文字断言按 sentinel 行的**已知主键定位**，而非断言整页 + 第一条（避免被既有初始数据行误判）。 + - **安全（C19）**：所有拼进 SQL 的值用参数化 / 严格转义（不裸字符串拼 INSERT；用占位符或对值做白名单）； + sentinel 用门自生成的受控格式（`[A-Za-z0-9_]`），**不**从文档 / DOM 取任意文本拼 SQL。 + +### step 2.5 — 鉴权 bootstrap（C2/C11/C12，确定性前置步骤，非「风险记录」） +ERP 绝大多数路由在登录后才可达（Spring Security / JWT 已在模板确认）。runner 在枚举前： +- 用 `config-vars.yaml admin_init`（A1 已锁的已知账号）或种子里写入的已知凭据，经 `docs/05` 登录端点**真实 + 登录**拿 JWT，注入 Playwright `storageState`。 +- `authState` 记录「以何角色登录、覆盖了哪些角色、未覆盖角色集」。多角色权限分叉至少覆盖 admin 一遍。 +- **登录失败归类为 `envError.kind='auth-failed'`（环境 race，走 retry）**，绝不当死控件 halt。 + +### step 3 — 枚举（可达性驱动，分母对账，非首帧快照，C13/C15） +- 每条路由用 Playwright 加载（带 storageState）后收集 DOM 真实存在的全部可交互控件 + （`button/a/input/select/[role=button]/@click` 等）与可见文字区域。 +- **覆盖判据 = 可达性驱动有界探索 + 来源对账**（不是首帧快照）： + - 分母 = step 1 推导的预期控件清单（从 prototype 链接/表单 action + FE spec 的 5 态状态机）。 + - 分子 = live 枚举到的控件。 + - 分母有、首帧无的控件，runner **尝试驱动到其出现态**：种子保证列表非空以触发行级操作、点击进入多步流程 + 下一屏 / 展开 dropdown / 切 tab 后做**二次枚举**。仍无法到达的记 `coverageGaps[reason='deep-control-not-driven']`， + **不静默判 green**。 + - 到达不了的路由（被重定向回登录 / 空壳）记 `coverageGaps[reason='unreachable-auth'|'unreachable-no-route']`， + 与「到达了但控件死」**严格区分**（前者 coverage-gap，后者才是 interactionFailure 硬 halt）。 +- **inert 过滤（C8）**：`disabled` / `[aria-disabled=true]` / `fieldset[disabled]` 内 / 计算样式 + `pointer-events:none` 的控件归为 `intentionally-inert`，**不纳入「必须有可观测效果」断言集**，但记入证据覆盖 + 清单（标注 inert + 推断禁用原因）。增强：对 disabled 提交类按钮，先用 sentinel 种子 / 输入把表单填到合法 + 态，观察是否解除 disabled——能解除即证明是活的且有正确门控；始终 disabled 且 spec 未说明的进 textIssues + 走 adjudicate，**不一律硬 halt**。 +- `routesReached` / `controlsEnumerated` 据实填。 + +### step 4 — 推导期望 +每控件给出预期可观测效果；每文字区域给出预期内容 + 来源（`literal` / `sentinel` / `i18n` / `semantic`）。 + +### step 5 — 断言（两层 + 可观测效果白名单，C6） +- **交互层**：点击 / 交互要求**可观测效果**，白名单（C6 扩充，避免误判生效按钮为死控件）： + - URL 变化 / `docs05` 网络调用（`page.on('request')` 比对预期端点）/ DOM 变更 / 校验信息 / 弹层 / toast； + - **原生对话框**：枚举前 runner 必须注册 `page.on('dialog')`，「弹出原生 confirm/alert/beforeunload」本身 + 计为一类合法可观测效果（危险操作的 `confirm()` 不处理会阻塞 → 误判 missing-docs05-call）； + - **下载** `page.on('download')` / **新标签** `page.on('popup')`/`target=_blank` 也是合法效果。 + - 无任何可观测效果 → `interactionFailures[kind='no-observable-effect']`；点击触发 JS 异常 → + `js-error`；console.error → `console-error`；应发未发 docs05 → `missing-docs05-call`。 + - 断言用 Playwright 的 **auto-waiting / `expect.poll`**（不用固定 sleep），从机制压低渲染时序 flake（C4）。 +- **文字层**：渲染对比推导期望。动态格对比对应字段的**唯一 sentinel**（不仅「等于某 sentinel」，而是「等于 + 该 region 推导期望字段的那个唯一 sentinel」，以抓绑错字段，C14）。 +- **绑定垃圾分级（C8，收窄锁定决策 4）**：`null`/`undefined`/`[object Object]`/`NaN`/lorem 出现在数据绑定位 + → `interactionFailures[kind='binding-garbage']`（高置信硬 halt）；「双花括号未渲染 / 空占位 `—` / 疑似 + i18n key（含点号标识符且无对应文案）」→ `textIssues[source='i18n'|'literal']` 走 adjudicate。i18n 场景额外 + 要求 runner 加载真实 locale 资源比对。 + +### step 6 — 证据落盘 + commit（F7） +写 `docs/superpowers/module-reports/frontend-phase-behavior-gate-r.md`（含推导期望、逐控件判定、 +覆盖率计数 `routesPlanned/routesReached/controlsEnumerated`、`authState`、`coverageGaps`、截图）并 commit。 +- **截图归档（C19）**：要 commit 的截图落到**已纳入版本管理的**目录（如 + `docs/superpowers/module-reports/assets/frontend-phase-behavior-gate/r/`），证据报告只引用已提交 + 路径，**不**引用 `.tmp/`（避免 commit 后链接断链）。`.tmp/behavior-gate/r/` 只放 spec/种子/runner/ + 原始截图，跑完即弃。 + +--- + +## 4. 失败 / 控制流（runBehaviorGate，与 testGate 骨架对齐，C2/C21/C22） + +> 评审 C21（失败语义与安全维度）指出原文「interactionFailures 非空即硬 throw」与「RED 自动重试 1 次辨 flake」 +> 自相矛盾——若一返回带 interactionFailures 就 throw，flake 重试根本没机会跑。**最终控制流显式分段**，并把交互 +> 层硬边界纳入 adjudicate 框架（`allowContinue:false`），与全仓「halt 经 adjudicator」收敛架构一致（C24）。 + +``` +1. attempt=1：派子会话跑 runner，收 BEHAVIOR_GATE_SCHEMA。 +2. 若 envError.kind != 'none'（端口冲突/起栈未就绪/种子错/鉴权失败/超时）： + 归类为环境 race → 与 testGate 同款：attempt=2 重跑一次；仍 envError → adjudicate(allowContinue:false, + 只在 retry/halt 间裁)，retry 再起独立 attempt。绝不把环境 race 当死控件。 + 测试库护栏触发的 HALT 例外：不重试、不仲裁，直接 throw（assertSafeId 同级）。 +3. 空覆盖检查（C20）：frontend-phase 存在但 (controlsEnumerated==0 || routesReached==0) → + 绝不 green，归为 envError(stack/auth/seed 起不来) 走 step 2 的 retry/halt；证据报告头部红字标注 + 「本次门未覆盖任何控件，原因=<...>」。 +4. interactionFailures（交互硬边界）： + - attempt=1 出现时【不立刻 throw】，先按 testGate 同款跑 attempt=2（独立证据文件 r2，辨 flake）。 + - 仅当 attempt=2 后 interactionFailures 仍非空，经 adjudicate(allowContinue:false) 在 retry/halt 间裁； + retry 用于「断言类红可在同一次起栈内重试单断言 / 环境抖动」，halt 用于真死控件。绝不 continue。 + - 仲裁可据 interactionFailures[].kind 区分「门自身未处理的弹窗类型 / 环境未就绪」与「真死控件」， + 前者倾向 retry，后者 halt。 +5. textIssues（文字软边界，按 source 分流 allowContinue，C11/C22）： + for-of textIssues： + - source=='sentinel'：actual≠唯一 sentinel 是客观 bug（门自己灌的确定值，非推导误报）→ + adjudicate(`behavior-text:${page}:${region}`, {expected,actual,source,allowContinue:false}, 'Behavior', round) + 仲裁只许 retry/halt，绝不 continue 放行绑错字段/显示错记录。 + - source ∈ {i18n,literal,semantic}：推导文案有误报风险 → + adjudicate(..., {allowContinue:true}, ...) retry=重判该条 / continue=recordDecisions 记入 + autonomousDecisions / halt=真内容 bug。 + - round 计数与 ADJUDICATE_MAX 上限按既有 adjudicate 循环惯例配（每条 site 独立计 round，上限 ADJUDICATE_MAX）。 +6. coverageGaps：写进证据报告 + recordDecisions（不单独 halt；空覆盖已在 step 3 兜底为 envError）。 +7. 全部通过（interactionFailures 空、sentinel textIssues 全消解、覆盖非空）→ 返回 { status:'green', ... }。 +8. 行为门 RED 发生在 milestone tag 之前，沿用 report 的 allowContinue:false 纪律，throw 自然冒泡到顶层 + try/catch → break，绝不带红进里程碑。 +``` + +**与既有原语的对齐**：交互层借 `testGate()` 同款 attempt=1→2 retry + adjudicate(allowContinue:false) +骨架；文字层借 `reviewWithFixLoop` 的逐条 for-of + adjudicate 先例（非 testGate 单裁面）。可选更省实现：把整门 +收敛为一次 `runStage(...)` 调用、让 `runStage` 现成的 adjudicate(retry/continue/halt)+ADJUDICATE_MAX 兜底 +软边界，交互硬边界单独前置判定 throw——但首选上面的显式分段以保证「环境 race 走 retry、死控件走 halt」的清晰。 + +--- + +## 5. behaviorGateContract（不直接套 featureStageContract('frontend')，C1/C6/C26） + +评审 C1/C6/C26 指出：`featureStageContract('frontend')` 的路径护栏明文「实现文件必须落 `frontend/`；命中 +`backend/`/`sql/`/`scripts/` 即越界硬停」（第 161-163 行），而行为门必须**运行** `scripts/setup-test-db.mjs`、 +起后端、生成 sql 语义种子——忠实执行该 contract 的子代理会把这些判为越界并自相矛盾。且 contract 还含「全部输出 +中文 / 缺值查找顺序 / 绝不留 TBD」等与门职责冲突的条款（门要写英文 sentinel / Playwright spec）。 + +**新增 `behaviorGateContract()`**（第三类：跨栈只读验证 + 临时产物），只保留真正通用的硬约束： + +``` +## 硬约束（行为门——只读验证门，非交互子代理） +- 你是 Workflow 派生的非交互子代理，物理上无法弹问，绝不尝试问人。 +- 全部输出文档使用中文（证据报告）；但生成的 Playwright spec / sentinel / SQL 种子可用英文标识符。 +- 作用域例外（关键）：本门为【只读验证门】。允许【运行（不可写）】scripts/setup-test-db.mjs、起后端/前端服务、 + 跑 playwright；唯一可写位置 = .tmp/behavior-gate/r/（spec/种子/runner）+ 证据报告及其 assets 目录。 + 改动 frontend/ / backend/ / sql/ 任何【源码】即越界硬停。把「运行 backend 服务」与「写 backend 实现」显式区分。 +- 缺值时优先自主决策继续并记入 decisions[]（与 featureStageContract 同口径）；仅无法自洽的硬事实才 halt。 +- sentinel / 端口 / 临时目录名由你在自身上下文确定性生成；【绝不】依赖 mjs 编排层提供 time/random（编排层禁用）。 +``` + +`behaviorGatePrompt(module, attempt)` = `behaviorGateContract()` + `commitBlock(证据路径+assets, 'docs(behavior-gate:frontend-phase:r): 行为门证据')` + step 0-6 指令 + `BEHAVIOR_GATE_SCHEMA` 输出契约。 + +--- + +## 6. report 前置接入（C23，闭合「按钮生效/文字正确」证据链） + +`reportPrompt` 前端分支（`coding.mjs:947`）现仅 Glob `${phaseId}-test-gate-r*.md` 并要求「最后一份 green」。 +behavior-gate 证据未进绿前置 → milestone tag 指向的 commit 报告对行为门「视而不见」。**扩展**： + +- 前端分支绿前置 Glob **追加** `frontend-phase-behavior-gate-r*.md`，按 attempt 升序，**最后一份必须 + status 非 RED**（与 test-gate 同纪律）；最后一份 red 立即 halt。 +- §⑤ flake 汇总纳入 behavior-gate 各 attempt（红→绿切换标注 flake）。 +- §⑧ 偏离清单纳入行为门的 `coverageGaps` + textIssues continue 记录 + 逐控件判定摘要 + `authState` 未覆盖 + 角色集，让 milestone 真覆盖「按钮生效 / 文字正确」的证据。 + +--- + +## 7. resume / 幂等（C25，接受全量重跑但收敛非确定性） + +- behavior-gate 夹在 frontend `testGate` 与 `report` 之间，**不自打独立 tag**（完成真值仍是 + `milestone/frontend-phase`）。接受代价：halt 后人工修复重跑 `coding-start` 时，Router 见 `frontend-phase` + 无 milestone tag → 整段重跑，各 FE 因 `req-done/` 已存在而 skip（OK），但 frontend `testGate` 与 + behavior-gate 完整重跑（含重起栈 + 全量枚举）。 +- **收敛即时推导的逐次漂移**：门入口先清 `.tmp/behavior-gate/` 整目录（避免跨 resume 串味）；每 attempt 用 + 独立子目录 `.tmp/behavior-gate/r/`（与证据文件 `-r` 对齐），跑前清空保证幂等。证据报告里 + 已落盘的推导期望可供人工审计；**不**要求 resume 复用上次推导（接受重推，但风险节记明漂移代价）。 +- **源码修复路径语义**（对齐 `coding.mjs:1148`）：behavior-gate 触发的修复若需改 FE 源码，须**先手动删除对应 + `req-done/` tag** 才会在重跑时重走 review；否则该 FE 跳过 review。门**自身不改源码**（只读验证门），文字 + bug 经 adjudicate；真要改码留给人工 / 重跑，设计在此显式提示。 + +--- + +## 8. coding.mjs 新增面汇总（实现清单） + +| 新增 | 位置 | 说明 | +|---|---|---| +| `BEHAVIOR_GATE_SCHEMA` | 与其他 schema 同段（第 64 行 GATE_SCHEMA 附近） | §2 形状，`additionalProperties:false`，复用 decisions[]/artifactPath 词汇 | +| `behaviorGateContract()` | `microStepContract`/`featureStageContract` 附近 | §5，只读验证门作用域例外 | +| `behaviorGatePrompt(module, attempt)` | `gatePrompt` 附近 | §3+§5，contract + commitBlock + step 0-6 + schema | +| `runBehaviorGate(module)` | `testGate` 附近 | §4 控制流：frontend-phase 守卫 → 清 .tmp → attempt 循环（envError retry / 空覆盖兜底 / interactionFailures attempt2→adjudicate(false) / textIssues 按 source 分流） | +| `meta.phases += {title:'Behavior'}` | 第 10-13 行 | Gate 与 Milestone 之间 | +| 顶层插桩 | `coding.mjs:1361` 之后、if 闭合前 | `phase('Behavior'); await runBehaviorGate(module)` | +| `reportPrompt` 前端分支扩展 | `coding.mjs:947/956/957` | §6 绿前置 + §⑤/§⑧ 纳入 behavior-gate | + +**运行时约束自洽（F6）**：`runBehaviorGate` 编排层不调用 `Date.now()`/`Math.random()`/`new Date()`；sentinel/ +端口/目录名由子代理生成；顶层 `return` 完好；用注入全局 `agent`/`phase`/`log`/`adjudicate`/`recordDecisions`。 +所有拼进 git/shell 的标识符（`attempt` 经 `Number()`+整数校验后拼路径）仍过既有安全口径；BEHAVIOR_GATE_SCHEMA +`additionalProperties:false`。 + +--- + +## 9. 残留风险（已知、接受或缓解） + +- 全栈 headless 起栈 + 逐路由枚举 + 鉴权 + 多步驱动，单 attempt 墙钟可能数分钟到十几分钟；flake ×2 + + adjudicate 再拉长。缓解：仅 testGate 绿后跑 + **runner 内单次起栈跑完所有路由（硬约束，绝不每路由重起栈）** + + auto-waiting + 整体墙钟上限（超时归 envError 走 retry）。无法把墙钟压到很低，接受。 +- 即时推导的路由分母 / 文字期望仍有 LLM 非确定性；sentinel 绑定类已收为确定性硬比对，i18n/literal/semantic + 类保留 adjudicate（设计自身权衡）。逐次推导漂移已记入 §7。 +- 多角色权限分叉：至少覆盖 admin，未覆盖角色集显式记 `authState` + §⑧；非 admin 角色专属按钮可能漏测。 +- 动态参数路由无种子可实例化时记 `coverageGaps[dynamic-route-no-seed]`，可降级但显式可见，不当已覆盖。 +- 测试库护栏依赖命名约定（含 test/_dev/_local）；若项目用非常规测试库名（如 `staging`）会被护栏挡下要求人工 + 确认——宁可误挡不可误删，接受。 + +--- + +## 拒绝的建议（无依据 / 过度工程，记明理由） + +- **「为 behavior-gate 自打独立幂等 tag（behavior-gate-pass/frontend-phase）」**（C25 选项）：拒绝。会新增 + 一类 resume 真值，与现有「milestone/req-done 两级 tag」体系叠加复杂度；用户锁定决策未要求更细断点，且全量 + 重跑成本已被「仅 testGate 绿后跑」摊薄。改为接受全量重跑 + 在 §7/§9 记明代价。 +- **「种子改为确定性 JS 生成（读 docs/03 解析后排序）而非 LLM 推导」**（C-确定性 issue B 选项）：部分采纳为 + *方向*但不强制实现。理由：锁定决策 2 明确「门运行时即时推导」，且新建确定性种子生成器是独立大工程（需复刻 + db-init 的 docs/03 解析 + FK 拓扑），超出本门范围。采纳其可落地内核——种子失败单独归类 `seedError` + + 结构化根因 + retry 带 guidance（§3 step2.4 / §4），把「同 docs/03 → 同种子」的非确定性收敛到「失败可诊断、 + sentinel 规则确定」，不强制改推导机制本身。 +- **「textIssues 一律升级 allowContinue:false」**：拒绝。会让 i18n/语义等价类误报变成不可恢复 halt，与锁定 + 决策 4「文字走 adjudicate 不硬 halt」冲突。改为按 source 二分（sentinel 硬、其余软），既守真 bug 又不卡死。 diff --git a/skills/coding/coding-start/SKILL.md b/skills/coding/coding-start/SKILL.md index 96868c9..fd2d1ab 100644 --- a/skills/coding/coding-start/SKILL.md +++ b/skills/coding/coding-start/SKILL.md @@ -23,6 +23,7 @@ allowed-tools: Read Glob Workflow Bash(git rev-parse *) Bash(git tag *) 后端测试闸 test-gate（RED 自动重试 1 次，仍 RED → halt） 前端功能循环 同一流水线，phase=frontend（FE-NN，限 frontend/） 前端测试闸 test-gate + 前端行为闸 behavior-gate（headless 全栈起栈+种子 sentinel，逐路由枚举：交互失效→halt，文字不符→仲裁） 跨模块记录 → 模块报告 → 里程碑（merge --no-ff + milestone/ tag） 任一模块 halt → fail-fast 停在该模块，修复后重跑本入口即可续跑 diff --git a/workflows/coding.mjs b/workflows/coding.mjs index 20fd3fd..3e2d2a6 100644 --- a/workflows/coding.mjs +++ b/workflows/coding.mjs @@ -9,7 +9,7 @@ export const meta = { description: 'Run the entire ERP coding phase autonomously and silently: per-module backend+frontend feature loops, test gate, milestone tag.', phases: [ { title: 'Router' }, { title: 'Backend' }, { title: 'Frontend' }, - { title: 'Gate' }, { title: 'Milestone' }, + { title: 'Gate' }, { title: 'Behavior' }, { title: 'Milestone' }, ], } @@ -65,6 +65,52 @@ const GATE_SCHEMA = { type:'object', additionalProperties:false, required:['status'], properties:{ status:{type:'string',enum:['green','red']}, failures:{type:'array',items:{type:'string'}} } } +// BEHAVIOR_GATE_SCHEMA：前端行为门（headless behavior-gate）返回。 +// 不杂交 GATE×STAGE_RESULT——复用既有词汇但独立成型：交互层 / 文字层 / 覆盖率 / 环境错误分别结构化， +// JS 据 source/kind 分流（交互硬 halt，文字按 source 二分 allowContinue，envError 走 retry）。 +// 设计：见 docs/design/2026-06-02-frontend-behavior-gate.md § 2。 +const BEHAVIOR_GATE_SCHEMA = { type:'object', additionalProperties:false, + required:['status','routesPlanned','routesReached','controlsEnumerated'], properties:{ + status:{type:'string', enum:['green','red']}, + routesPlanned:{type:'integer'}, // router 声明的路由数（覆盖率分母来源） + routesReached:{type:'integer'}, // 实际带鉴权加载成功的路由数 + controlsEnumerated:{type:'integer'}, // live 枚举到的控件数（空覆盖必须可见） + authState:{type:'string'}, // 以何角色登录 / 覆盖角色 / 未覆盖角色集 + // 交互层硬边界：no-observable-effect / js-error / console-error / missing-docs05-call / binding-garbage + interactionFailures:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['page','control','kind','detail'], + properties:{ + page:{type:'string'}, control:{type:'string'}, + kind:{type:'string', enum:['no-observable-effect','js-error','console-error','missing-docs05-call','binding-garbage']}, + detail:{type:'string'} } } }, + // 文字层软边界：source 决定 allowContinue（sentinel 客观 bug 不可 continue；i18n/literal/semantic 可 adjudicate continue） + textIssues:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['page','region','expected','actual','source'], + properties:{ + page:{type:'string'}, region:{type:'string'}, + expected:{type:'string'}, actual:{type:'string'}, + source:{type:'string', enum:['sentinel','i18n','literal','semantic']} } } }, + // 覆盖率缺口：写证据 + recordDecisions，不单独 halt（空覆盖由 controlsEnumerated==0 兜底） + coverageGaps:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['page','reason','detail'], + properties:{ + page:{type:'string'}, + reason:{type:'string', enum:['unreachable-auth','unreachable-no-route','deep-control-not-driven','dynamic-route-no-seed']}, + detail:{type:'string'} } } }, + // 环境错误（与业务断言失败严格区分，走 retry）：none 表示无环境问题 + envError:{ type:'object', additionalProperties:false, + required:['kind'], + properties:{ + kind:{type:'string', enum:['port-conflict','stack-not-ready','seed-error','auth-failed','timeout','none']}, + detail:{type:'string'}, ports:{type:'string'}, pids:{type:'string'} } }, + // decisions[]：复用 STAGE_RESULT 形状，缺值自主决策日志 + decisions:{ type:'array', items:{ type:'object', additionalProperties:false, + required:['question','choice','rationale'], + properties:{ + question:{type:'string'}, choice:{type:'string'}, rationale:{type:'string'}, + confidence:{type:'string', enum:['high','medium','low']} } } }, + artifactPath:{type:'string'} } } + // ── 微步骤 schemas（runBranchSetup / runMilestone / runCrossModule 用）───────── const WT_SCHEMA = { type:'object', additionalProperties:false, required:['clean'], properties:{ @@ -472,6 +518,106 @@ function gatePrompt(module, phase, attempt = 1) { ].filter(Boolean).join('\n') } +// ---- 前端行为门（headless behavior-gate）---- +// 设计权威：docs/design/2026-06-02-frontend-behavior-gate.md。frontend testGate 绿后、report/milestone 前跑， +// 仅 frontend-phase 聚合模块触发。门是**跨栈只读验证 + 临时产物**的第三类 stage：不套 featureStageContract('frontend') +// （其路径护栏命中 backend/sql/scripts 即越界硬停，与门必须运行 setup-test-db / 起后端 / 生成 SQL 种子自相矛盾）。 + +// behaviorGateContract：门的硬约束。非交互；证据报告用中文但 spec/sentinel/SQL 可英文标识符； +// 作用域例外——允许**运行**（不可写）scripts/setup-test-db.mjs / 起后端前端 / 跑 playwright， +// 唯一**可写** = .tmp/behavior-gate/r/ + 证据报告及 assets；改 frontend//backend//sql/ 源码即越界硬停。 +function behaviorGateContract() { + return [ + '## 硬约束（非交互行为门子代理）', + '- 你是 Workflow 派生的**非交互子代理**，物理上无法弹出 AskUserQuestion / 等待人类输入。**绝不要尝试问人**。', + '- 你是**跨栈只读验证门**：用真实运行（起后端 + 起前端 headless + Playwright 枚举）证明「每个按钮/点击真的生效、每段文字显示正确内容」，**不是**实现功能、**不是**改源码。', + '- 缺值查找顺序：`config-vars.yaml` → `docs/04-技术规范.md § 零` → `docs/05-API接口契约.md` → `docs/03-数据库设计文档.md` → `prototype/`（前端布局/交互权威）→ `frontend/`（router 配置 / package.json / playwright.config.*）→ 现有代码。仍查不到时**优先自主决策继续**，把决策写进证据报告显著位置并登记到返回 `decisions[]`（`{question,choice,rationale,confidence}`）。', + `- **作用域例外（关键）**：本门为跨栈验证，明确允许**运行**（不修改）以下命令——\`node ${ROOT}/scripts/setup-test-db.mjs\`、起后端服务（spring-boot:run 等）、起前端 headless（vite / playwright webServer）、跑 Playwright；唯一允许**写入**的路径是 \`${ROOT}/.tmp/behavior-gate/r/\`（spec/种子 SQL/runner，跑完即弃）+ 证据报告 \`${ROOT}/docs/superpowers/module-reports/frontend-phase-behavior-gate-r.md\` + 其 assets（截图归档到 \`${ROOT}/docs/superpowers/module-reports/assets/...\`）。`, + `- **越界硬停**：**绝不**编辑 \`frontend/\` / \`backend/\` / \`sql/\` 下的任何源码文件，也**绝不**编辑 \`${ROOT}/scripts/\` 下的脚本——只许**运行** scripts/setup-test-db.mjs。区分「运行 backend 服务」（允许）与「写 backend 实现」（越界）。命中越界即以 \`status:red\` + \`envError\` 或写清阻塞点结束。`, + '- 红线：**绝不**伪造断言通过；**绝不**留 `TBD` / `TODO`；自主默认必须可被现有证据支撑且记入 `decisions[]`。', + '- 证据报告**使用中文**；spec / sentinel 标识符 / SQL 可用英文（`[A-Za-z0-9_]`，受控格式，不取任意文本）。', + '- **运行时确定性**：sentinel 值 / 端口 / 临时目录名一律由你确定性派生（按列类型 / config-vars 端口 / attempt 序号），**绝不**依赖时间戳 / 随机数。', + ].join('\n') +} + +// behaviorGatePrompt：门子代理的完整流水线提示（step0-6 + schema）。 +// attempt：1 = 首跑；2.. = flake / 环境 race retry。每 attempt 独立 .tmp 子目录 + 独立证据文件。 +function behaviorGatePrompt(module, attempt) { + const id = module?.id ?? 'frontend-phase' + const tmpDir = `${ROOT}/.tmp/behavior-gate/r${attempt}` + const evidence = `docs/superpowers/module-reports/frontend-phase-behavior-gate-r${attempt}.md` + return [ + `# behavior-gate — 前端行为门（headless，attempt=${attempt}）`, + '', + behaviorGateContract(), + '', + '## 目标', + `用真实全栈运行证明前端 \`${id}\` 的「每个按钮/点击都真的生效、每段文字都显示正确内容（right context）」。`, + `单个子会话内**收敛完成**：起栈 → 逐路由枚举 + 两层断言 → teardown。期望即时推导（prototype/ + REQ + docs/05），**不**持久化为契约，但推导期望写进已提交证据报告。`, + attempt > 1 ? `- 本次 = 第 ${attempt} 次（上一次 red 或 envError；本轮用于辨识 flake / 等环境就绪）；证据**写到独立文件 r${attempt}** 不要覆盖前一次。` : '', + '', + '## 运行机制（无常驻进程跨会话；起栈→跑→teardown 收敛进单 runner）', + `- **入口清目录（跑前第一步，去串味，§7/C25）**：${attempt === 1 + ? `本次 attempt=1 → 先删除整个 \`${ROOT}/.tmp/behavior-gate/\` 目录（清掉所有历史 attempt 残留 runner/种子/spec，避免跨 resume 串味），再新建本 attempt 子目录 \`${tmpDir}/\`。` + : `本次 attempt=${attempt} → 仅删除/清空本 attempt 子目录 \`${tmpDir}/\`（保证幂等，不动其它 attempt 的已提交证据无关的临时残留），再新建。`}用确定性、跨平台方式删除（如 \`fs.rmSync(path, { recursive:true, force:true })\` 后 \`fs.mkdirSync(path, { recursive:true })\`），**仅限上述受控路径**，绝不删 \`.tmp/behavior-gate/\` 之外的任何路径。`, + `- 你在 \`${tmpDir}/\` 写一个一次性 runner（如 \`run.mjs\`），用 spawn 起进程树、轮询就绪、\`finally\` 中 **kill 全部子进程**并透传结构化结果。**绝不**让前台 spring-boot:run / vite 挂死会话——它们永不退出，必须 spawn 到后台进程树 + 轮询健康端点 + 跑完 teardown。`, + `- \`${tmpDir}/\`（含子目录）已被仓库 \`.gitignore\` 忽略，是唯一临时写区；跑完即弃，只提交证据报告 + assets。`, + '', + '## step0 探测起栈能力', + `- 读 \`${ROOT}/docs/04-技术规范.md § 零\` + \`${ROOT}/frontend/package.json\` + \`${ROOT}/frontend/playwright.config.*\` + \`${ROOT}/config-vars.yaml\`。`, + '- (a) 有 `webServer` / `reuseExistingServer` → 复用 playwright 起前端；(b) 无 → runner 自负起**后端 + 前端**（项目通常无既有 e2e 起栈，须显式探测 + 自负起栈）；无法判定 / 起栈失败 → `envError.kind="stack-not-ready"`。', + '', + '## step1 路由真值发现（覆盖率分母）', + `- 主来源 = \`${ROOT}/frontend/\` 的 router 配置（Vue Router / React Router \`routes\`，用 Grep 定位）；\`routesPlanned\` = router 声明的路由数。`, + '- 由 `prototype/` + 关联 REQ 卡片 + `docs/05` 推导**每路由的预期控件与文字来源**（作覆盖率分母）；每路由标注所需登录角色。', + '- 带参动态路由用**种子已知主键**实例化；无法实例化 → 记 `coverageGaps[reason="dynamic-route-no-seed"]`，不静默判 green。', + '', + '## step2 安全护栏 + 起栈四段严格时序（schema 由 Flyway 在后端启动时才建）', + `1) **测试库安全护栏（确定性，先于一切）**：读 config-vars 的数据库名；若**不匹配测试库命名**（库名须含或以 \`test\` / \`_test\` / \`_dev\` / \`_local\` 结尾）→ runner 非零退出，返回 \`status:red\` + \`envError.kind\` 留空走 HALT 语义（在 detail 写明「测试库护栏：库名 非测试库，拒绝 DROP，留人工确认」）。**绝不**对非测试库跑 setup-test-db。`, + `2) \`node ${ROOT}/scripts/setup-test-db.mjs\`（DROP+CREATE 空库）。DROP 前按 \`${tmpDir}/*.pid\` / 既知端口优雅回收残留进程。`, + '3) **起后端**：spawn 到后台 + 轮询 `/actuator/health` 或登录端点 200（Flyway 在此 apply 建 schema）；端口取 config-vars，先探测占用，占用则回收残留或退到动态空闲端口 + 把 baseURL 注入下游。', + '4) **此时才跑种子**：按 `docs/03-数据库设计文档.md` 派生 **FK 有序 INSERT** 种子（先父后子）。失败 → `envError.kind="seed-error"` + 结构化根因（缺列 / 撞唯一键 / enum 越界 / FK 序错 / 类型截断），**不**混进交互 RED。', + ' - **sentinel 规则**：按列类型派生类型合法且可辨识的值——字符串列逐字段唯一编码（如 `CUST_NAME_S001`，抓绑错字段）+ 行序号保 UNIQUE；数值列用高位魔数；enum 列从 docs/03 值域取并标注。插入前扫 Flyway / config-vars 既有初始数据（admin_init 等）键，sentinel 主键偏移到不冲突区；断言按 sentinel 行已知主键定位。所有 SQL 值参数化 / 白名单转义，sentinel 用受控 `[A-Za-z0-9_]` 格式。', + '5) **起前端 headless**：(a) playwright webServer / (b) spawn + 轮询 ready；端口同样探测 + 动态回退。', + '- `finally` **硬要求 kill 全部子进程**；端口 + pid 写入 `envError.ports` / `envError.pids`（即便成功也回填，便于审计）。', + '', + '## step2.5 鉴权 bootstrap（确定性前置）', + '- 用 config-vars `admin_init` 或种子已知凭据，经 `docs/05` 登录端点**真实登录**拿 JWT，注入 Playwright `storageState`；`authState` 记角色覆盖（覆盖 / 未覆盖角色集）。', + '- 登录失败 = `envError.kind="auth-failed"`（环境 race，走 retry），**绝不**当成死控件。', + '', + '## step3 枚举（可达性驱动 + 分母对账，非首帧快照）', + '- 每路由带 `storageState` 加载，收集 DOM 真实控件与文字区域。分母 = step1 推导清单，分子 = live 枚举。', + '- 分母有但首帧无的控件：runner 尝试**驱动到出现态**（种子保列表非空触发行级操作 / 进多步流程下屏 / 展开 dropdown / 切 tab 后二次枚举）；仍不可达 → `coverageGaps[reason="deep-control-not-driven"]`，不静默判 green。到不了的路由 → `coverageGaps[reason="unreachable-auth"|"unreachable-no-route"]`，与「到达了但控件死」严格区分。', + '- **inert 过滤**：`disabled` / `[aria-disabled]` / `fieldset[disabled]` / `pointer-events:none` 归 intentionally-inert，不入「必须有效果」断言集但记证据；disabled 的提交类按钮先填合法态观察是否解除 disabled。', + '- `routesReached` / `controlsEnumerated` 据实填（空覆盖必须可见）。', + '', + '## step4 推导期望', + '- 每控件预期可观测效果；每文字区域预期内容 + 来源（`literal` / `sentinel` / `i18n` / `semantic`）。', + '', + '## step5 断言（两层 + 可观测效果白名单）', + '- **交互层可观测效果白名单**：URL 变化 / docs05 网络调用（`page.on("request")` 比对端点）/ DOM 变更 / 校验信息 / 弹层 / toast / 原生对话框（枚举前注册 `page.on("dialog")`，confirm/alert/beforeunload 计合法效果，防 confirm 阻塞误判 missing-docs05-call）/ 下载（`page.on("download")`）/ 新标签（`page.on("popup")` / `target=_blank`）。', + ' - 无任何效果 → `interactionFailures[kind="no-observable-effect"]`；JS 异常 → `js-error`；`console.error` → `console-error`；应发未发网络调用 → `missing-docs05-call`。断言用 auto-waiting / `expect.poll`，**不用**固定 sleep。', + '- **文字层**：动态文字格对比该 region 字段的唯一 sentinel（抓绑错字段）。', + '- **绑定垃圾分级**：`null` / `undefined` / `[object Object]` / `NaN` / `lorem` 出现在绑定位 → `interactionFailures[kind="binding-garbage"]`（硬 halt）；双花括号未渲染 / 空占位 `—` / 疑似 i18n key → `textIssues`（走 adjudicate；i18n 类额外加载真实 locale 比对）。', + '- **文字不符按来源分流到 source**：绑定 sentinel 不符 → `source="sentinel"`（客观 bug）；i18n key / 字面 / 语义类 → `source="i18n"|"literal"|"semantic"`。', + '', + `## step6 证据落盘 + commit（运行时行为，沿用 test-gate 证据 commit 习惯）`, + `- 写 \`${evidence}\`：推导期望 / 逐控件判定 / routesPlanned-Reached-controlsEnumerated / authState（含未覆盖角色集）/ coverageGaps / 截图。`, + `- 截图归档到**已纳入版本管理**的 \`docs/superpowers/module-reports/assets/...\`（**不要**引用 \`.tmp\` 防断链）。`, + `- 若本次 \`status:red\` 或存在 envError，证据**头部用红字标注原因**。`, + commitBlock(`${evidence} docs/superpowers/module-reports/assets`, + `docs(behavior-gate:r${attempt}): 前端行为门证据`), + '', + '## 输出（必须符合下发的 BEHAVIOR_GATE JSON schema）', + '- `status`: `green`（交互层无失败 + 文字层无 sentinel 类失败 + 无 envError + 覆盖非空）| `red`。', + '- `routesPlanned` / `routesReached` / `controlsEnumerated`: 整数，据实填（空覆盖必须可见）。', + '- `interactionFailures` / `textIssues` / `coverageGaps`: 见 schema 的 kind / source / reason 枚举。', + '- `envError`: 无环境问题填 `{ "kind": "none" }`；有则填对应 kind + detail + ports + pids。', + '- 做过任何自主默认 → `decisions[]` 逐条登记。`artifactPath` = 证据报告项目根相对路径。', + '- 不要返回额外字段（schema 是 `additionalProperties:false`）。**不要在本步骤内自动重试**——重试由上层 Workflow 控制。', + ].filter(Boolean).join('\n') +} + // ---- 微步骤 prompt builders（runBranchSetup / runMilestone / runCrossModule 用）---- // 每个 prompt 单职责、短文本；返回严格 schema；执行（action）步统一返回 ACTION_RESULT_SCHEMA。 function microStepContract() { @@ -493,6 +639,7 @@ function microStepContract() { // ============================================================================ const ADJUDICATE_MAX = 3 // 单个 site 的仲裁轮上限；超出则确定性 halt（防无限循环） +const BEHAVIOR_GATE_PASS_MAX = ADJUDICATE_MAX * 4 // 行为门 ①②③ 整体收敛轮上限：每次文字层 retry 跳回从头过硬门，超出则确定性 halt（防无限循环） const adjGuidance = (g) => g ? `\n\n## 仲裁返回的纠正指令（本次重跑必须遵守）\n${g}` : '' // 全流程自主决策日志：stage 缺值时不停而是挑默认/解读，登记在此，随结果回传供人工事后审阅。 @@ -945,6 +1092,9 @@ function reportPrompt(module) { '', '## 前置', `- 验证上游 test-gate 绿：Glob \`${ROOT}/docs/superpowers/module-reports/${phaseId}-test-gate-r*.md\`，**按 attempt 数字升序**读取每一份。**最后一份必须 green**；只要最后一份 red 立即 halt。中间存在 red→green 切换 = flake，需在 § ⑤ 标注。`, + fe + ? `- **验证上游 behavior-gate（前端行为门）绿**：Glob \`${ROOT}/docs/superpowers/module-reports/frontend-phase-behavior-gate-r*.md\`，**按 attempt 数字升序**读取每一份。**最后一份必须非 RED**（status:green / 无 envError）；最后一份 red 立即 halt。各 attempt 的 flake / 环境 race / 文字 continue 记录纳入 § ⑤ 汇总。` + : '', '', '## 收集输入（取摘要而非正文）', fe @@ -953,8 +1103,8 @@ function reportPrompt(module) { `- § ② "FE 完成清单"：扫 \`${ROOT}/docs/superpowers/{specs,plans,reviews}/<日期>-FE-*.md\`，按 FE-NN 顺序列出。`, `- § ③ 文件变更：\`git -C ${ROOT} diff --stat <默认分支 main/master>...HEAD\`（三点 diff，区间 = 功能分支 \`frontend-phase\` 自默认分支分叉以来的全部改动）。`, '- § ④ 数据库使用表 / § ⑥ Migration / § ⑦ 跨模块：填 `N/A（前端阶段）`。', - `- § ⑤：把 \`${ROOT}/docs/superpowers/module-reports/frontend-phase-test-gate-r*.md\` 全部（按 attempt 排序）摘要汇总。若 attempt 数 > 1 且首次 red 末次 green → 在 § ⑤ 顶部明确标注 \`flake-detected: r1 red, r${'<最后一次>'} green\`，并附首次失败用例与最终绿色记录链接。`, - '- § ⑧ 偏离清单：额外审查"实际渲染 DOM 与各 FE 关联原型主结构的差异"，逐 FE 列出。', + `- § ⑤：把 \`${ROOT}/docs/superpowers/module-reports/frontend-phase-test-gate-r*.md\` 全部（按 attempt 排序）摘要汇总。若 attempt 数 > 1 且首次 red 末次 green → 在 § ⑤ 顶部明确标注 \`flake-detected: r1 red, r${'<最后一次>'} green\`，并附首次失败用例与最终绿色记录链接。**另把 \`frontend-phase-behavior-gate-r*.md\` 各 attempt（按序）的 flake / 环境 race（envError）/ 文字 continue 记录一并纳入 § ⑤ 汇总**。`, + `- § ⑧ 偏离清单：审查"实际渲染 DOM 与各 FE 关联原型主结构的差异"，逐 FE 列出；**额外纳入 behavior-gate 报告的 \`coverageGaps\` + 文字 \`textIssues\` 的 continue 记录 + 逐控件判定摘要 + authState 未覆盖角色集**。`, '- § ⑪ 下一模块预览：填"上线 / 部署后续步骤"。', ].join('\n') : [ @@ -1229,7 +1379,7 @@ async function reviewWithFixLoop(id, phase, verifyResult, specPath) { // opts.phase = grp（'Backend'/'Frontend'）是 harness UI 分组；domain phase 见 agents/code-reviewer.md。 const r = await agent( reviewPrompt(id, phase, round, lastVerifySummary, specPath) + adjGuidance(reviewGuidance), - {label:`review:${phase}:${id}:r${round}`, phase: grp, schema: REVIEW_SCHEMA, agentType:'code-reviewer'} + {label:`review:${phase}:${id}:r${round}`, phase: grp, schema: REVIEW_SCHEMA, agentType:'erp-workflow:code-reviewer'} ) reviewGuidance = '' // 已消费 @@ -1299,6 +1449,138 @@ async function testGate(module, phase) { return g } +// ---- 前端行为门控制流（runBehaviorGate）---- +// 设计：docs/design/2026-06-02-frontend-behavior-gate.md § 4。 +// 仅 frontend-phase 触发（入口二次保险）；每 attempt 独立 .tmp 子目录（门子代理负责清/写）。 +// 失败分层： +// - envError != none（端口/起栈未就绪/种子/鉴权/超时）= 环境 race：同 testGate 跑 attempt=2；仍 envError → +// adjudicate(allowContinue:false, retry/halt)；retry 再起独立 attempt；绝不当死控件。 +// - 空覆盖（controlsEnumerated==0 || routesReached==0）→ 绝不 green，归 env race 走 retry/halt。 +// - interactionFailures（含 binding-garbage）= 交互硬边界：attempt=1 出现不立刻 throw，先跑 attempt=2 辨 flake； +// 仍非空 → adjudicate(allowContinue:false, retry/halt)，绝不 continue。 +// - textIssues（软边界）：逐条 for-of —— source=='sentinel' → adjudicate(allowContinue:false)（客观 bug，只许 retry/halt）； +// source∈{i18n,literal,semantic} → adjudicate(allowContinue:true)（continue 时 recordDecisions 记入 autonomousDecisions）。 +// - coverageGaps：写证据 + recordDecisions，不单独 halt。 +// RED 在 milestone tag 前 throw 冒泡到顶层 try/catch → break，绝不带红进里程碑。 +async function runBehaviorGate(module) { + // 入口二次保险：仅 frontend-phase 聚合模块跑行为门（同 runMilestone / reportPrompt 惯例）。 + const fe = module?.id === 'frontend-phase' + if (!fe) { log(`behavior-gate: ${module?.id ?? ''} 非 frontend-phase，跳过行为门`); return } + const lbl = (a) => `behavior:frontend-phase:r${a}` + + let attempt = 1 + let bg = await agent(behaviorGatePrompt(module, attempt), {label: lbl(attempt), phase:'Behavior', schema: BEHAVIOR_GATE_SCHEMA}) + recordDecisions('behavior-gate:frontend-phase', bg.decisions) + + // 共享重跑：每次 retry 都开一个独立 attempt（独立 .tmp/r 证据），刷新 bg + 记录决策。 + // 文字层 retry 也走这里，确保重跑后能跳回 ①②③ 重新整体过硬门（见下方收敛循环），绝不拿旧快照继续。 + const rerun = async () => { + attempt += 1 + bg = await agent(behaviorGatePrompt(module, attempt), {label: lbl(attempt), phase:'Behavior', schema: BEHAVIOR_GATE_SCHEMA}) + recordDecisions('behavior-gate:frontend-phase', bg.decisions) + } + + // helper：环境 race / 空覆盖归一处理——先跑一次 flake 重试，仍异常则 adjudicate(allowContinue:false)。 + const envBlocked = (r) => { + const ev = r.envError && r.envError.kind && r.envError.kind !== 'none' ? r.envError : null + const emptyCov = (Number(r.controlsEnumerated) === 0) || (Number(r.routesReached) === 0) + return { ev, emptyCov, blocked: !!ev || emptyCov } + } + const ifails = (r) => Array.isArray(r.interactionFailures) ? r.interactionFailures : [] + + // ① 环境 / 空覆盖硬门：仍异常 → 仲裁（allowContinue:false → retry/halt）。 + // 抽成闭包，便于文字层 retry 后由收敛循环重新整体校验（绝不带空覆盖 / envError 判 green）。 + const enforceEnv = async () => { + let envState = envBlocked(bg) + for (let adj = 1; envState.blocked && adj <= ADJUDICATE_MAX; adj++) { + const reason = envState.ev + ? `behavior-gate envError=${envState.ev.kind}: ${envState.ev.detail || ''}` + : `behavior-gate 空覆盖：routesReached=${bg.routesReached} controlsEnumerated=${bg.controlsEnumerated}（绝不带空覆盖判 green）` + const verdict = await adjudicate('behavior-gate-env:frontend-phase', + { problem: reason, envError: bg.envError || null, ports:(bg.envError||{}).ports, pids:(bg.envError||{}).pids, allowContinue:false }, 'Behavior', adj) + if (verdict.action !== 'retry') throw new Error(`HALT behavior-gate-env frontend-phase: ${verdict.rationale || reason}`) + await rerun() + envState = envBlocked(bg) + } + if (envState.blocked) throw new Error(`HALT behavior-gate-env frontend-phase: ${ADJUDICATE_MAX} 轮仲裁后仍环境异常 / 空覆盖`) + } + + // ② 交互层硬门（含 binding-garbage）：仍非空 → 仲裁（allowContinue:false → retry/halt），绝不 continue。 + // 每次 retry 重跑后可能新冒环境问题，由收敛循环回到 ① 兜底，避免把环境 race 当死控件。 + const enforceInteraction = async () => { + for (let adj = 1; ifails(bg).length && adj <= ADJUDICATE_MAX; adj++) { + const summary = ifails(bg).map(f => `[${f.kind}] ${f.page}:${f.control} — ${f.detail}`).join('; ') + const verdict = await adjudicate('behavior-gate-interaction:frontend-phase', + { problem:`behavior-gate 交互层失败（含 binding-garbage 硬边界，绝不 continue）：${summary}`, + interactionFailures: ifails(bg), allowContinue:false }, 'Behavior', adj) + if (verdict.action !== 'retry') + throw new Error(`HALT behavior-gate-interaction frontend-phase: ${verdict.rationale || summary}`) + await rerun() + await enforceEnv() // 重跑后先过 ① 环境兜底，再回到本门继续辨交互 + } + if (ifails(bg).length) + throw new Error(`HALT behavior-gate-interaction frontend-phase: ${ADJUDICATE_MAX} 轮仲裁后交互层仍有失败`) + } + + // attempt=1 出现环境/交互问题不立刻 throw——先跑独立 attempt 辨 flake，再进入硬门收敛。 + if (envBlocked(bg).blocked || ifails(bg).length) await rerun() + + // ①②③ 收敛循环：任何文字层 retry 重跑都跳回此处，重新整体校验 + // envError → 空覆盖 → interactionFailures → textIssues（while 而非 for-of 快照）， + // 杜绝「文字 retry 后用旧数组继续、且新 bg 携带非空 interactionFailures/envError 滑过硬门」的逃逸。 + // softPassed：已被仲裁 continue 放行（降级）的 region，重跑后即便仍在 textIssues 也不再追问，避免死循环。 + const softPassed = new Set() + let converged = false + for (let pass = 1; pass <= BEHAVIOR_GATE_PASS_MAX && !converged; pass++) { + // ① 环境 / 空覆盖（硬门） + await enforceEnv() + // ② 交互层（硬门，含 binding-garbage） + await enforceInteraction() + + // ③ 文字层（软边界，按 source 分流）：while 取当前 bg 第一条未决 textIssue。 + // source=='sentinel' → allowContinue:false（门自灌确定值，绑错字段 / 显示错是客观 bug，只许 retry/halt）； + // source∈{i18n,literal,semantic} → allowContinue:true（continue 时 recordDecisions 记入决策日志）。 + const regionKey = (x) => `${x.page || '?'}::${x.region || '?'}` + const pickIssue = () => (Array.isArray(bg.textIssues) ? bg.textIssues : []) + .find(x => x && !softPassed.has(regionKey(x))) + let needRerun = false + let ti + while ((ti = pickIssue())) { + const hard = ti.source === 'sentinel' + const site = `behavior-gate-text:frontend-phase:${ti.page || '?'}:${ti.region || '?'}` + const verdict = await adjudicate(site, + { problem:`文字不符（source=${ti.source}${hard ? '，sentinel 客观 bug 不可 continue' : '，可 continue 降级'}）：${ti.page}:${ti.region} 期望=${JSON.stringify(ti.expected)} 实际=${JSON.stringify(ti.actual)}`, + textIssue: ti, allowContinue: !hard }, 'Behavior', pass) + if (verdict.action === 'continue' && !hard) { + // continue：把放行决策记入 autonomousDecisions（供人工事后审阅），并标记该 region 已软放行。 + recordDecisions(site, [{ question:`文字不符 ${ti.page}:${ti.region}（source=${ti.source}）`, + choice:'continue（仲裁判可安全前进）', rationale: verdict.rationale || '', confidence:'low' }]) + softPassed.add(regionKey(ti)) + continue // 处理同一 bg 内的下一条 + } + if (verdict.action !== 'retry') + throw new Error(`HALT ${site}: ${verdict.rationale || `文字不符 source=${ti.source}`}`) + // retry：重跑整门取最新判定，并跳回 ①②③ 重新整体过全部硬门（绝不拿旧快照继续）。 + await rerun() + needRerun = true + break + } + if (!needRerun) converged = true // 无 retry → 文字层已收敛（全软放行 / 全消失） + } + if (!converged) throw new Error(`HALT behavior-gate-text frontend-phase: ${BEHAVIOR_GATE_PASS_MAX} 轮收敛后文字层仍未解决`) + + // ④ coverageGaps：写证据 + recordDecisions（不单独 halt；空覆盖已在 ① 兜底）。 + for (const g of (Array.isArray(bg.coverageGaps) ? bg.coverageGaps : [])) { + if (!g) continue + recordDecisions('behavior-gate-coverage:frontend-phase', + [{ question:`覆盖缺口 ${g.page}（${g.reason}）`, choice:'记录不阻断', rationale: g.detail || '', confidence:'low' }]) + } + + if (bg.status === 'red') + throw new Error(`HALT behavior-gate-red frontend-phase: 门返回 status:red 但未归入交互/文字/环境分支——拒绝带红进里程碑`) + log(`behavior-gate: frontend-phase green（routesPlanned=${bg.routesPlanned} routesReached=${bg.routesReached} controls=${bg.controlsEnumerated} authState=${bg.authState || '?'}）`) +} + phase('Router') // Router 语义断言（feItems/reqs 互斥）+ id 形状硬约束（防 shell 注入：id 直接拼入 `git ... ${id}`）。 // id 形状（assertSafeId）是**安全护栏**——失败立即硬 halt，绝不重试绕过。 @@ -1359,6 +1641,8 @@ for (const [idx, module] of todo.entries()) { await featureLoop(module.feItems, 'frontend') phase('Gate') await testGate(module, 'frontend') + phase('Behavior') // 前端行为门：testGate 绿后、report/milestone 前（仅 frontend-phase 聚合） + await runBehaviorGate(module) } phase('Milestone') // report allowContinue:false：reportPrompt 的前置硬验证含"最后一次 test-gate 必须 green，红则 halt"—— -- libgit2 0.22.2