agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/notes/gate-diet.md

@@ -0,0 +1,75 @@
+# 门禁减重立项（gate-diet，2026-10-23）
+
+> 目标：在**不降验证语义**的前提下压本地关单墙钟。当前全量墙钟 ~130–193s（并发池 j3 膝点，see
+> verify.mjs 编排注释），关键路径 = backend-test。本文件是**立项基线与实验清单**——执行按 perf 技能
+> 单变量纪律走（`.agents/skills/perf/SKILL.md`），每项实验独立提交、独立复测、过噪声带才算数。
+
+## 1. 基线（2026-10-23，源 `.agents/verifications.jsonl` 216 行机器台账）
+
+证据快照：`tmp/perf/gate-diet-baseline.json`（本机生成；下表为同数据摘要，12 逻辑核）。
+
+| 门 | 近10均 | 峰值 | 场次 | 备注 |
+|---|---|---|---|---|
+| backend-test | **100s** | 214s | 69 | 关键路径；`dotnet test --no-build`（diet③ 已消双构建）；**负载敏感**：安静窗 91s vs 忙窗 146s |
+| ledger-invariant | 90s | 107s | 55 | **历史数据**——diet⑥（2026-10-21）起该门已退出本地路径（`envSkipIds` 条件 `!TF_BUILD` 不分 scope/full 档），末次实执行 2026-10-21 04:57（head 8a5799f8）；本地全量/差分均 envSkips 记录跳过，执法面 = CI main 全量 + pre-commit --staged |
+| engine-tests | 74s | 133s | 73 | npm test 53 套件并发 12；最慢三套件 check-loop.test 39–53s / check-ledger-invariant.test 30–45s / check-loop-rev.test 32–44s |
+| secrets-scan | 30s | 36s | 73 | gitleaks 全仓全史扫描 |
+| check-loop | 20s | 34s | 73 | — |
+| frontend-build | 17s | 26s | 71 | 本地档已瘦身为 vue-tsc（diet④） |
+| **全量墙钟** | **~130–193s** | 193s | — | j2 178 / j3 122 / j4 129 / j6 137（并发膝点实测在 3） |
+
+**噪声带结论（先于任何优化）**：backend-test 同日两次全绿运行 91s ↔ 146s（差 60%）——共享 dev 库
+（集成测试连真库）+ 同机并行会话是主要噪声源。**任何 <60s 的 backend-test「改善」都不可信**，复测须
+安静窗 + ≥3 次取中位（number-vetting 口径）。这本身是立项发现 #0：**先消噪声源（专用测试库 TEST_DB_CONN，2026-10-23 库供给已落地 = `Deve_CSS_SuHao`，见 runtime-env §6.5），减重测量才有可信地基**。
+
+## 2. 实验清单（按预期收益 ÷ 风险排序；一次一个变量）
+
+| # | 假设 | 单变量改动 | 预期 | 风险/取舍 |
+|---|---|---|---|---|
+| 0 | 噪声源污染测量与稳定度 | 配置专用测试库连接（TEST_DB_CONN，runtime-env §6.5 已登记机制） | 集成测试不碰共享 dev 库：消除撞号/超时脆红（2026-10-22 三连红即此类）+ 噪声带收窄 | 需 DBA 供库；纯环境改动不动代码 |
+| 1 | ~~backend-test 内部串行~~ → **改判**：Tests 独跑 1657 用例仅 3s，91–146s 几乎全是 IntegrationTests（605 用例，真库往返主导）——双进程并行收益 3–5s < 噪声带，不单独立项 | ~~双进程并行~~ | ≈5s | 无（结论见 §4） |
+| 2 | ~~xunit 并行度未开满~~ → **折叠进 #0**：两 csproj 均无并行限制（默认集合并行已开），真约束是**真库数据互踩** | 依赖 #0 | #0 后另估 | 与 #0 合并评估 |
+| 3 | ~~engine-tests 慢三套件重复 spawn~~ → **改判**：套件内可省 30s+（check-loop.test 12 处 spawn 为最长杆），但 engine-tests 被 backend 链在 j3 池**完全吸收**，墙钟零收益；待 backend 链 <60s 再启动 **→ 2026-10-23 复测：调度/分片旋钮已到拐点（并发 12、K=8），剩余杠杆是 135 个场景的 node 启动/夹具成本，需代码级改造（见 §4）** | 套件内 fixture spawn 共享 | 墙钟 0（段内 -30~50%） | 测试独立性 |
+| 4 | secrets-scan 全史扫 | ~~gitleaks 基线 + 增量~~ | 30s → ~5s | **✘ 不采纳（2026-10-23 owner 委托裁定，"按推荐解法"）**：30s 收益不在关键路径（关键路径 = backend-test 100s）；且 2026-10-21 密钥口径本地退役后，secrets-scan 全史扫是**唯一**的历史泄露执法面——增量化对存量泄露失明，削的是安全语义不是耗时。保持全史扫 |
+| ~~5~~ | ~~ledger-invariant 全量档本地执行~~ | — | — | **✘ 撤回（2026-10-23，前提证伪）**：diet⑥ 的 envSkipIds 条件（`!TF_BUILD`）本就**不分 scope/full 档**——ledger-invariant 末次实执行 2026-10-21 04:57（head 8a5799f8），此后本地全量/差分均 envSkips 记录跳过。立项基线误把台账**历史聚合值**（近10均 90s）读成现行行为。教训已固化：看板门表增「末次执行」列（40b6a9e7 后续提交），聚合均值不再掩盖「门已退役出本地路径」的事实 |
+| 6 | 并发膝点复测 | 顺延至 #0 与 backend 链实质变化之后——当前变量未动，复测无信息量 | — | 纯测量，零代码 |
+| 1' | （#0 解锁后的新杠杆）IntegrationTests 库隔离并行：每 collection 独立 schema/库，提 MaxParallelThreads 或分区并发 | 依赖 #0 供库形态 | 605 用例 90–140s，DB 往返主导——隔离后并行度才有意义 | 分区工作量真实存在；#0 落地后单独立项评估 **→ 2026-10-23 落地并实测（见 §4；隔离单位 = 库副本，进程级分区）** |
+
+## 3. 验收与回滚
+
+- 每项实验：基线 3 次 / 改动 / 复测 3 次（安静窗）/ 结论落账于本文件 §4；改善未过噪声带 → 回滚或记「未证实」。
+- 门禁减重的红线：**门数不減、断言不減**（只减耗时不减语义）；任何「删门」类提议不在本立项范围
+  （走机制退役流程，单源 mechanism-registry.md）。
+- 总目标（软）：全量墙钟 193s 峰值 → **≤90s**（j3 池），以 #0–#3 全落地为前提（#4/#5 已裁定不动）。
+
+## 4. 实验落账（执行时逐行追加）
+
+| 日期 | 实验 | 基线 | 复测 | 结论 |
+|---|---|---|---|---|
+| 2026-10-23 | #4 secrets-scan 增量 | 30s（近10均） | — | **不采纳**：非关键路径 + 削唯一历史泄露执法面（安全语义 > 耗时）；owner 委托"按推荐解法" |
+| 2026-10-23 | #5 ledger-invariant 全量档 | 误读的 90s | — | **撤回**：前提证伪——diet⑥ 已覆盖全档（envSkips 实证，末次实执行 2026-10-21）；基线误读历史聚合值，看板门表补「末次执行」列作防再犯 |
+| 2026-10-23 | #1 双项目并行 | Tests 独跑 3s（1657 用例）/ Integration ≈90–140s（605 用例） | — | **不采纳**：max−sum ≈ 3–5s 低于噪声带；backend-test 权重 ≈ IntegrationTests，杠杆收敛到 #0（专库）→ 1'（库隔离并行） |
+| 2026-10-23 | #2 xunit 并行度 | csproj 无并行限制（默认集合并行已开） | — | **折叠进 #0**：约束是真库数据互踩，非调度配置 |
+| 2026-10-23 | #3 引擎慢三套件 | engine-tests 74s / check-loop.test 39–53s | — | **挂起**：套件内可省 30s+，但 engine-tests 被 backend 链（~112s）在 j3 池完全吸收，墙钟零收益；待 backend 链 <60s 再启动 |
+| 2026-10-23 | #0 专用测试库（库供给落地） | IntegrationTests 对共享 dev 库（噪声带 60%） | 对 SuHao **605/605 全绿**（564→598→602→605 四轮收敛；详见数据维护台账 2026-10-23 行） | **完成**——1'（IntegrationTests 库隔离并行）具备评估前提 |
+| 2026-10-23 | #1' 集成测试库隔离分区（进程级） | 串行 605/605：测试 53s / 墙钟 55s（专用库安静窗）；backend-test 门（单测+集成）≈59s | 3 分区：集成段 21.3–27.2s，wrapper（单测串行+分区并行）30.2–32.8s，3 轮全绿（1657 单测 + 605 集成） | **采纳**：进程内并行先实测挂死（共享 `MM_SYS_MaterialCode` / `MM_INV_InventoryRecord` 行 X 锁互等，SQL 默认无锁超时，4 线程 6 分钟不收敛）——隔离单位改为独立库副本，入口 `scripts/verify/backend/run-integration-partitions.mjs`，库供给见 runtime-env §6.5。附带发现：单测 `PurchaseOrderNoConcurrencyTests.并发取号_序号互不重复且连续` 在与分区并发负载下 2/3 轮红（既有脆点，非本次引入）→ wrapper 保持单测串行 |
+| 2026-10-23 | #3 调度旋钮（run-tests 并发） | 并发 12：墙钟 91.2–92.6s，check-loop.test 64.4–65.6s | 并发 8：104–111.5s；6：110.2–115.3s；16：113.9–118s；20：110.5–130s | **不采纳改动**：12 已是拐点，升降均更慢（套件池 + 分片叠加超订）。并发 12 保留 |
+| 2026-10-23 | #3 分片旋钮（check-loop.test K） | K=8 独跑：44.1–44.9s | K=6：47.8–56s；12：59.9–78s；16：51.9–55.7s | **不采纳改动**：K=8 已是拐点。run-tests 内 65s 与独跑 44.5s 的差 = 套件池争用，非分片不足 |
+| 2026-10-23 | #3 verify 争用复测（K=4） | verify 全量 139.4s / engine-tests 133.9s（K=8） | 未取得 | **阻断**：secrets 门红（外部分支历史泄漏 `frontend/.npmrc`，非本轮改动）→ fail-fast。先处置密钥后再复测 |
+| 2026-10-23 | #3 剩余杠杆判定 | 135 场景 × 每场景 1 次 `node check-loop.mjs` 启动 + git 夹具 | — | **需代码级改造**：in-process/resettable check-loop 或场景批处理，预计可省 10–20s；属多文件重构，另行评估 |
+| 2026-10-27 | #7 ledger-invariant 历史扫描（体检 P0-A） | 全量档实测 479.1s；剖分为 293 次 `git log`（159.4s）+ 2397 次 `git show`（122.7s）+ 895 次 `git log -1 --format=%P`（14.7s）+ 其余 | **4.0s**（冷跑，exit 0，裁决输出与旧实现逐行一致） | **采纳**：① 一次 `git log -m --full-history --name-only` 建「路径→提交」倒排（0.8s，`-m` 必需——合并提交默认不输出文件列表，漏 280/293 路径；等价性已逐路径验证 293/293 一致）；② `cat-file --batch` 批量读 blob（2397 次 show 122.7s → 0.5s）；③ `rev-list --parents` 批量取父表；④ 顺手纠正上文 #5：本门**并未**退出本地路径——`verify-scope.LEDGER_TOUCH_RE` 使「触及 `confirmations.d/` 即回列」，而关单每单新建分片，故几乎每单都命中（近 30 天 76/110 绿行真跑了本门，占墙钟中位 37%、峰值 95%）。改后该门不再是关键路径，`envSkipIds` 是否保留留待下一轮裁定 |
+| 2026-10-23 | #3 分片 LPT（实测权重） | 轮转独跑 43.4s；套件池配对 A 106–115s（check-loop 73–78.9s） | LPT 独跑 35–37.7s；套件池配对 B 103.7–112.4s（check-loop 69.9–79.9s） | **回退·未证实**：独跑改善超噪声带，但套件池墙钟仅快约 2.5s（< ±3s），check-loop 时间互有胜负——按 perf 红线不保留。权重/LPT 代码已回退；in-process 仍是唯一剩余杠杆 |
+| （未开始） | #6 膝点复测 | | | 顺延至 #0/#1' 后 |
+| 2026-10-24 | #3 SLOW_FIRST 保留依据补账（复核 D2） | 126d39fe 声明 78.86→65.07s（单轮、未过噪声带纪律） | 全量 3 轮：94.0 / 96.1 / 90.8s（中位 94.0s，exit 0 ×3） | **保留·补账**：套件数已 65→74（+7 技能自带套件、+verify-scope 等），与声明时点绝对值不可比，65.07 无法原样复测；三轮离散 5.3s 属负载噪声量级（同时段有并行会话）。无 A/B 对照不判优劣——如需严格裁决须临时移除 SLOW_FIRST 对照另立实验；本轮不据以回退（与上行分片回退同守「无证据不保留/不回退」对称纪律） |
+| 2026-11-06 | 快照刷新（P0-5，测量非实验） | 旧窗口 2026-10-22~28（62 条，full 为主）：墙钟中位 127.0s / p90 308.4s / 峰值 841.1s | 新窗口 2026-10-30~11-06（193 条，含 scope）：中位 **33.4s** / p90 46.4s / 峰值 164.3s | **记录**：① 中位下降含窗口构成效应（旧 full 为主、新含 33% scope），不可直接相减；② 单门同口径可比：ledger-invariant 182.4→7.8s、backend-test 51.0→14.3s、secrets-scan 26.3→0.8s、check-loop 24.2→3.7s；③ 门表已变：engine-tests / workflow-metrics / workflow-index / engine-map / effective-policy 退出本地路径（现 16 门）；④ 关键路径转移到前端三门（frontend-build 16.8s / frontend-lint 11.1s / frontend-unit-test 5.2s）；⑤ 后续 P1 实验以本窗口为基线 |
+| 2026-11-06 | 档位使用面测量（P0-1，更正） | — | 2026-10-29 起（unitOnly 标记可靠窗）all-gates 绿行 218：scope 裁门 76（wall 中位 20.8s）、默认档未裁门 136（37.0s）、显式 `--full` **6**（51.8s）；默认档+scope 占 **97.2%** | **记录·更正**：上一版把 10-29 前无 unitOnly 标记的默认档误判为显式 full（称 113 次 / 204.8s）——判据必须限定 10-29 后窗口，已更正；脚本缺省 diff 档（2026-10-22）行为面本就正确，`test.md` §1 口径修正属文档对齐；已加 ledger `mode` 字段（verify.mjs:670）供后续直接判定 |
+| 2026-11-06 | 重档语义修复（P0-1 续测衍生，owner 裁定「直推 main 与 PR→main 都要集成执法」） | 修复前 `verify.mjs --full --list --verbose`：backend-test = `run-backend-tests.mjs --unit-only` | 修复后：`--full` = `run-backend-tests.mjs`（含集成）；默认档 / 中档仍 `--unit-only` | **已修**：门链加 `fullTier`（显式 `--full` 或默认档回落）分支返回未改写的 GATES；两处兜底回落同享（`scopeMode=null` 时置 `fullTier=true`）；`unitOnly` 标记判据由 `!explicitFull` 改 `!fullTier`。根因 = 2026-10-29 46326cf8 把 `--unit-only` 加进默认档时未排除 `--full`，致 CI main（`--full`）与 main 直推的 CI 侧无集成执法（pre-push `--select-range` 一直有，上一版记录误称「pre-push 无覆盖」）。CI 已备 `TEST_DB_ALLOW_DEV=1` 逃生（azure-pipelines.yml），修复后该逃生真正生效 |
+| 2026-11-06 | P1-a vue-tsc 增量（frontend-build 门） | `vue-tsc -b` 3 轮 14.2 / 14.2 / 14.5s（无增量收益；tsbuildinfo 仅 8KB stub，无 program 段） | `vue-tsc --noEmit -p tsconfig.app.json --incremental`：冷 14.3s → 热 **6.6s**（node config 1.6s）；改后 `npm run type-check` 3 轮 7.4 / 7.3 / 7.2s | **采纳**：`frontend/package.json` type-check 改增量双配置（覆盖与 CI `vue-tsc -b` 等价：app + node）。正确性实证——注入新文件类型错误 → exit 2 点名；改动既有文件 → exit 2；还原 → exit 0。副作用：tsbuildinfo 8KB → 378KB（含 program 段）；并行会话同跑 verify 对同一 tsbuildinfo 有写竞态（与 `-b` 同性质，tsc 遇损坏 fail-loud） |
+| 2026-11-06 | P1-b eslint --cache | 全仓 lint 3 轮 8.4 / 8.1 / 8.0s | 全仓 `--cache`：冷 8.9s → 热 **2.3 / 2.2s**；但 scoped lint（2 文件）无 cache 2.3 / 2.2s、加 cache 2.4 / 2.2s = 零收益 | **不采纳**：默认档 lint 已按变更面裁剪（近 25 轮实测 3.4–5.6s，2026-11-05 起），cache 对 scoped 无效；全仓 lint 只在 CI main（clean checkout 恒冷）与罕见本地 full 跑，收益面太窄，且引入缓存产物 + 陈旧风险。证据留此，若 full 档本地化再评估 |
+| 2026-11-06 | P1-c check-loop 导入成本（addedDates 全史扫描） | kit 冷导入 3.6–4.3s，其中 `git log --diff-filter=A --format=@%aI --name-only`（全仓全史）3.0–3.6s；5 段本体合计仅 0.27s | 收窄到 `-- workflow` 后：git log 2.2s、kit 导入 2.4s、check-loop 整体 3.05s（原 4.0s） | **采纳（部分）**：`check-loop-kit.mjs` 的 addedDates 加 `-- workflow`（消费方全是 workflow 文档，语义不变）。**段并行不可行**：5 段合计 0.27s / 4.0s，且段体是 spawnSync 同步调用（并行需改 async + 共享 blockers/warnings 顺序变化）。**剩余 2.2s = 历史行走**：实测 `git log <range>..HEAD -- workflow` 仅 75ms（5 提交）——磁盘缓存（HEAD 增量合并）可再省 ~2s，但引入失效逻辑正确性风险，待 owner 裁定 |
+| 2026-11-06 | P1-d vitest 默认池（frontend-unit-test 门） | `vitest run` 交错基线 8.1 / 7.8s（default≈forks） | `--pool=threads` 6.8 / 6.2s；maxWorkers 8→8.2s、4→8.5s、2→13.5s（加大无益）；改后 `npm run test:unit` 6.3 / 7.7 / 6.6s，247 用例全过 | **采纳**：`frontend/vitest.config.ts` 加 `pool: 'threads'`（12 核机上 ~−15%）。未做分片：单进程内已并行，`--shard` 需外部多进程编排，收益不抵复杂度 |
+| 2026-11-06 | P1-e check-loop addedDates HEAD 增量磁盘缓存（P1-c 续，owner 裁定做） | kit 冷导入 3.6–4.3s；check-loop 3.05s（P1-c 收窄后） | 缓存命中 **0.93s** / HEAD 前进（range）**0.99s** / 损坏重建 3.1s；三种路径输出逐字节相同 | **采纳**：`.agents/cache/added-dates.json`（`{root, head, dates}`，tmp+rename 原子写）；失效键 = root + HEAD 祖先关系 + 缓存完整性；git 失败不写、沿用旧值。实测连续 verify 同行头率仅 **13.1%**——故必须做 range 增量而非「HEAD 未动才跳过」 |
+| 2026-11-06 | P1-f ledger-invariant 增量窗口 | 7.6s = historyIndex 1.7s + parentMap 2.4s + refs 1.6s + warmBlobs 2.1s + 其余 0.8s | `--no-walk` 后全量 **5.5s**；增量窗口：HEAD 未动 **2.8s** / HEAD~1..HEAD **3.7s**；裁决等价（全量 vs 窗口问题集逐条相同，均 0 条） | **采纳**：① `parentMap` 加 `--no-walk`（rev-list 默认列全部祖先：200 sha → 4584 行 / 350ms；no-walk → 200 行 / 119ms，8 批 −1.9s）；② `.agents/cache/ledger-invariant.json` 记「上次绿跑 HEAD」，失效键 = root + baseline + 脚本 sha256 + HEAD 祖先关系；红跑不写，`--staged` 路径不读写。**残留地板 = historyIndex 1.7s**（路径枚举 + withHistory 依赖全史索引）——索引本身亦可 HEAD 增量缓存，待下轮 |
+| 2026-11-06 | P1-g rule-budget 批量预取 | `--all` 4.1–6.8s（逐文件 2 次 cat-file spawn × ~40 文件 = 80 次）；`--staged` 0.30–0.44s | `--all` **0.29–0.52s**（一次 `--batch-check` 取尺寸 + 一次 `--batch` 取内容）；`--staged` 不预取（0.38–0.44s，与原状相同）；两档输出逐字节相同 | **采纳**：`.agents/scripts/rule-budget.mjs` 加批量预取（`__preSize`/`__preContent`，索引→HEAD→工作区优先级原样保留）；`--staged` 跳过预取——该档只查暂存触及条目，预取全表反而更慢，且过滤口径与主循环共用、不复制以防漂移 |
+| 2026-11-06 | P1-h ledger-invariant 历史索引 HEAD 增量缓存（P1-f 续） | 空窗口下 2.6s，其中全史索引 `git log` 1.2s + 解析 0.5s | 索引命中 + 空窗口 **1.4s**；全窗口扫描 5.65s（vs 无缓存 6.43s）；输出 A===B 逐字节相同、问题集 A===C 相同 | **采纳**：`.agents/cache/ledger-history-index.json`（`{root, scriptHash, head, index}`）；HEAD 未动 → 零 git；前进 → 只走区间并追加（全史升序，区间提交更新 → 追加保序）；回退/损坏 → 全量。索引是「哪些提交存在」的事实、与裁决无关，故红跑也写。verify 实测 ledger-invariant **7.5s → 1.45s** |
+| 2026-11-06 | P1-i wiki-consistency 门数缓存 | 门 ~1.0s（standalone）/ 5.4s（verify 并行负载）；其中 `checkNarrativeClaims` 511ms = 两次 spawn `node verify.mjs --list`（各 ~250ms：node 启动 + 模块加载） | 门 **0.55–0.57s**（−45%）；verify 实测 5.4s → **<1.2s**（跌出前六）；输出逐字节相同 | **采纳**：`gen-narrative-claims.mjs` 的 `collectSources` 加 `.agents/cache/gate-counts.json`（`{root, verifyHash, all, engine}`）——门数只取决于 verify.mjs 的 GATES 数组，按内容哈希失效；缓存缺失/哈希不匹配/写失败一律回落逐次 spawn（原语义，不新增失败面）。另：门体多轮 `readdirSync`+`statSync` 已改 `withFileTypes`（Dirent 直判，symlink 回落 statSync 保语义），但实测那部分不是瓶颈（~260ms） |

package/templates/engine/.agents/notes/pr-review-cost-discipline.md

@@ -0,0 +1,48 @@
+# 评审成本纪律：面板只跑一次，并发会话分槽
+
+> **退役注记（2026-11-09，owner 指令）**：PR 面板自动门已拆——pre-push / CI / pr-create 不再强制评审台账。
+> 本页保留为**手动跑面板**的成本纪律，fast 档实测数据留档；编排入口移至 `.agents/commands/pr-review.md`。
+
+来源：2026-11-07/08 出库表头附件交付（run `pr-8fb73ea` / `pr-9e50909` / `pr-741f609` / `pr-6b535e0` 四轮面板，实测 ~2.5 小时，其中两轮完全作废）。`pr-review` 脚本只写「怎么跑」，本页写「什么时候跑、跑几次」——**流程约束，不重复工具细节**。
+
+## 规则
+
+1. **一次评审原则**：同一交付批次的面板评审**只跑一次**。顺序固定为
+   **整改全部落地 → 提交 → `plan` → finder/verifier → `dispose` → `summary` → 推送**。
+   禁「边评审边改」：`run.json` 的 `diffHash` 绑定 base..head，head 一变台账即失效，必须整轮重跑。
+2. **拿到 findings 后先改完再重开**：本轮确认项（`confirmed`）一次性改完并提交，再对**新的 head** 起新一轮；
+   不允许「改一条 → 重评 → 再改一条」（每轮 3 lens，2026-11-08 档 3 减配）。
+3. **先看 dispose 结论再决定改不改**：`waived` / `deferred` / `rejected` 的项不产生代码改动，
+   不要为它们改 head（改了就白跑一轮）。
+4. **并发会话必须分槽**：同一台机器上多个会话/多个 agent 并行时，各自设 `SHIPYARD_SLOT`
+   （端口槽与派生规则单源：`runtime-env.md` §6.1b）。共用一个槽会同时顶「工作区文件」与「分支 HEAD」，
+   评审期间 head 漂移 = 台账失效（本次实测另一会话在同分支追加了 `a4b347a02` / `02d269a79` / `c77f50b44`）。
+5. **引擎面提交不跑面板**：范围只落 `.agents/` `.githooks/` `.codebuddy/` `.trae/` `workflow/` `wiki/` `docs/`
+   与根配置时不值得起面板（原 pre-push 引擎面豁免随 2026-11-09 自动门退役，改人工把握）；
+   手动起面板前发现范围纯引擎/文档 → 这是文档任务，别跑面板。
+
+## 判定清单（起面板前逐条自答）
+
+- [ ] 本轮改动是否**已全部提交**？工作区是否只剩与本批无关的其它任务文件？
+- [ ] 是否**没有**待改的 confirmed finding？（有 → 先改，别起面板）
+- [ ] 本会话是否独占端口槽 / 分支？（不独占 → 先设 `SHIPYARD_SLOT` 或换分支）
+- [ ] 改动范围是否真的含业务面？（纯引擎/文档 → 不值得跑面板）
+
+任一条为「否」，起面板就是浪费。
+
+## 成本事实（供判断，2026-11-08 实测）
+
+| 动作 | 耗时 | 备注 |
+|---|---|---|
+| 单轮面板 finder（6 lens；2026-11-08 起减配 3 lens） | 8–27 min（6 lens 时实测） | 单份 brief 最大 131 KB（内嵌 diff 80 KB + base 50 KB） |
+| 单轮面板 verifier | 12–21 min | 改后：默认 1 票，Important/security 追加 1 票 |
+| `pre-push` 本地门 | 改前 110–130 s / 改后 15–20 s | 集成档默认交 CI（`PREPUSH_RUN_INTEGRATION=1` 可本地复现） |
+| 一次「改完就重评」的返工 | +15–30 min | 本次因顺序倒置浪费两轮（~33 min） |
+| fast 档单轮面板（--fast；单镜头单票，目标 ≤5 min） | **实测 377s**（零仓库读 finder 2 次工具调用 343s + 脚本 34s；首跑含队列 640s） | 模型延迟是地板，超硬顶按 fast-timeout 收口；判据与编排契约：`.agents/scripts/pr-review.mjs` 头注 fast 档节 + config `fast` 节 |
+
+## 相关单源
+
+- 评审面板机制与命令：`.agents/scripts/pr-review.mjs`（--help）+ `.agents/commands/pr-review.md`
+- 确认门与三件套顺序：`.agents/notes/process-order-rule.md`
+- 端口槽与并发：`.agents/notes/runtime-env.md` §6.1b（**本页不复述端口数值**）
+- 门禁卡口一览：`.agents/notes/engine-map.md`

package/templates/engine/.agents/notes/process-order-rule.md

@@ -0,0 +1,21 @@
+# 顺序红线：先定级 → 三件套 → 确认 → 才动手
+
+来源：2026-11-03 流程倒置事件（incident `workflow/incidents/2026-11-03-po-pml-outbound-guards.md`、`workflow/papercuts.md` 同日条目）。`new-task.md` 首屏只留一句指针，正文细节在此。
+
+## 规则
+
+1. **动手前**跑 `new-task.md` §1 两问定级（结构面 → L3；契约或共享口径 → L2；都没有 → L1）。一次报多项缺陷时**逐项定级，取最高**。
+2. 命中 L2 / L3：先落 `workflow/incidents/`（缺陷类）或 `workflow/intents/`，再 `spec`，再 `plan`，**逐份 `confirm-doc` 通过后才允许改代码**。L1 也要先有 plan（写清判据）。
+3. **禁「先改后补档」**：确认门的语义是「用户点头的那份方案先于实现存在」。事后补档无法还原时间序 = 绕过确认门；一旦发生，须在 incident「门禁失效分析」与 `workflow/papercuts.md` 双落登记，并在提交信息中指明。
+4. 判级不确定时默认**按高一级处理并先落文档**，不要先写代码再回填级别。
+
+## 为什么文档状态门拦不住，以及现在哪道门拦得住
+
+- 级别是判断而非机器可判信号：同一改动可能是「纯新增只读字段」（L1）或「既有语义收紧」（L2），hook 无法从 diff 推断级别。
+- 确认指纹只校验文档状态与承诺面，不校验发生顺序。`confirm-doc` 在实现之后调用，文档门仍会通过。
+- 顺序的机器信号在提交时刻：`.agents/hooks/check-confirm-order.mjs`（2026-11-08 档 2-D 起由 `.githooks/commit-msg` 调用——pre-commit 读不到提交消息；合并跳过改由脚本探测 `MERGE_HEAD` 状态文件）。暂存的 `backend/` 源码、`frontend/src` 的 vue/ts、`tests/**/*.cs`、数据维护 SQL，必须逐条出现在**状态为 approved** 的 `workflow/plans/` 正文里，或命中豁免：①L0 车道（消息体含非空 `L0:` 行且产品文件 ≤5）②覆盖性 plan 与本批同暂存（L1 单笔提交，`done` 亦可）。`done` 的**历史** plan 不算覆盖；`draft` 也不算。squash、rebase、cherry-pick 跳过。
+- 定级本身仍靠执行者。先改后补档若绕过本门（路径没写进 plan、或提交不经 git 钩子），仍双落 incident + papercuts。
+
+## 复现痕迹（2026-11-03）
+
+- 实现提交 `302226b8` 先于 `83b7015f` 的三件套补档；check-loop 期间无阻塞（因门只看状态），说明顺序面无机器保护。

package/templates/engine/.agents/notes/runtime-env.local.example.md

@@ -0,0 +1,21 @@
+# 运行时环境登记（本机专用模板——复制为 `runtime-env.local.md` 后按实况填写）
+
+> **本文件是入库模板；真身 `runtime-env.local.md` 已 git-ignore，各机自登记、不提交、不共享。**
+> 机理与解析顺序见 `runtime-env.md` §6.3。消费方（运行时自动读取「工具」表行）：
+> 5 个 dwf 工作流（`.zcode/workflows/*.dwf.ts`）、`scripts/verify/e2e/browser-resolve.mjs`、`.agents/scripts/check-local-gates.mjs`。
+> 未登记的工具有内置标准安装位置探测（node/dotnet/git 逐候选 `--version` 试跑、浏览器 fs 存在性探测）；
+> **登记仅用于覆盖非标准安装位置**——clone 后先跑 `node .agents/scripts/check-local-gates.mjs`，
+> 按其回显判断哪些工具需要登记。
+
+| 工具 | 本机路径 | 备注 |
+|---|---|---|
+| node | <例：D:/Program Files/NodeJs/node.exe> | 标准安装（C:/Program Files/nodejs）无需登记 |
+| npm-cli | <例：D:/Program Files/NodeJs/node_modules/npm/bin/npm-cli.js> | 可省：dwf 未登记时随 node 目录自动派生 |
+| dotnet | <例：C:/Program Files/dotnet/dotnet.exe> | 标准位置无需登记 |
+| git | <例：C:/Program Files/Git/cmd/git.exe> | 标准位置无需登记 |
+| bash | <例：C:/Program Files/Git/bin/bash.exe> | 仅 `bash` 不在 PATH 的机器需要；取退出码 `& "<此路径>" -c '…; echo EXIT=$?'` |
+| browser | <例：C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe> | 仅浏览器装在非标准位置时需要；或用环境变量 `CHROME_PATH` |
+
+## 其他本机事实（供 agent 阅读，无机器消费方）
+
+- <例：终端默认 PowerShell；本机 Chrome 83 内核过旧禁用；CPU 核数等实测口径>

package/templates/engine/.agents/pipelines/_TEMPLATE.md

@@ -0,0 +1,75 @@
+# Workflow 编排机制 — 编排脚本 + steps 扩展点
+
+> kit 的跨宿主编排机制：`.agents/pipelines/` 下的编排脚本承载编排语义（依赖分层 / 并行 / 重试 / gate / 用户确认门 / run journal），**宿主 AI 经 AGENTS.md 常驻指令自动加载并按语义执行**——有子智能体的宿主并行 fan-out，没有的顺序自做，验收不变。零宿主协议适配：机制只依赖所有宿主共有的四样本领（读 AGENTS.md、读仓库文件、跑终端命令、子智能体）。
+
+## 自动加载（AGENTS.md 常驻指令）
+
+> 多工作包编排——用户要跑编排、或 plan 执行多工作包时：读 `.agents/pipelines/` 编排脚本按本文档语义执行；自定义步骤在 `steps/`。
+
+## 编排脚本（`.agents/pipelines/<主题>.md`）
+
+frontmatter（`name` / `description` / `concurrency` 默认 2）+ 一张 stages 表（`human` 列可选——不用确认门的可省该列，保持 9 列）：
+
+```md
+---
+name: 并行修两域
+description: 后端+前端并行实现 → 汇聚过测试 → 部署验证（step）→ 独立评审
+concurrency: 2
+---
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| backend | — | implementer | — | 实现后端 X | src/api/** | 项目测试过 | | | 1 |
+| frontend | — | implementer | — | 改前端 Y | web/** | 构建过 | | | 0 |
+| gate-all | backend,frontend | — | — | — | — | — | node .agents/scripts/verify.mjs | | |
+| confirm-deploy | gate-all | — | — | 用户对话内确认可上 staging | — | 一句「可以」 | | 用户确认 | |
+| deploy-check | confirm-deploy | — | 部署验证 | env=staging | | 部署命令 exit 0 | | | 0 |
+| review | deploy-check | independent-reviewer | — | 评审两域改动 | | 符合 plan 与判据 | | | 0 |
+```
+
+**stage 四形态**（互斥，恰填一项）：
+
+| 形态 | 判据 | 执行 |
+|------|------|------|
+| role 派单行 | `role` 非空 | 派子智能体（`task` 目标 / `files` 授权清单 / `accept` 验收判据写进派单头 + 红线行） |
+| step 行 | `step` 非空 | 宿主 AI 读 `steps/<step>.md` 按指引执行，`task / params` 列传参 |
+| gate 行 | `gate` 非空（role/step/human 空） | 终端跑命令，非零即中止 |
+| human 确认门行 | `human` 非空（其余形态列空） | 宿主 AI **停下向用户询问**（`task` 列 = 问什么、`accept` 列 = 通过判据），通过才派下层；驳回 → 中止汇总。**不派子智能体**（机器判据层面落实「子智能体不跨确认门」，取代早前 role 行伪装确认门的写法） |
+
+**编排语义**（执行口径，全宿主同一）：`after` 空 = 第 0 层；一层全 ok 才派依赖它的下一层；层内按 `concurrency` 分批——有子智能体的宿主并行 fan-out，没有的顺序自做（验收标准不变）；失败且 `retries` > 0 → 重派（全新上下文）；重试超限 / gate 非零 / human 驳回 → 中止后续、汇总报告失败项。human 行无重试语义（retries 视作 0）。
+
+**run journal**（断点续跑与重试计量）：每个 stage 每次尝试出结果（pass / fail / blocked）即记一行；中止后重跑先看 status——已 pass 的 stage 不重跑，从就绪层续：
+
+```bash
+node .agents/scripts/wf-journal.mjs add --wf <编排名> --stage <id> --status pass --form human   # fail/blocked 同式；--form ∈ role|step|gate|human
+node .agents/scripts/wf-journal.mjs status --wf <编排名>                                        # 已完成 / 就绪（含重试就绪×N）/ 待定
+```
+
+journal 落 `.agents/cache/orchestration-runs.jsonl`（本地运行态，可丢弃；同 run 同 stage 多行按末次生效，attempt 自动计次；`--new-run` 新起一轮）。
+
+## steps 扩展点（`.agents/pipelines/steps/<名>.md`）
+
+kit 定义的扩展机制：文件名即步骤名（steps 目录即注册表），项目把自己的领域动作（部署 / 迁移 / 审计上报…）注册进来，编排脚本 step 行引用即用。
+
+```md
+---
+params: env（目标环境）；timeout-min（可选，默认 10）
+---
+# 步骤 — 部署验证
+
+1. 跑终端命令：`npm run deploy -- --env <env>`，非零即步骤失败并回报 stderr 尾段
+2. 跑冒烟检查：`curl -fsS https://<env>.example.com/healthz`
+3. 回报：部署版本号 + 冒烟结果
+```
+
+- frontmatter `params`：参数约定（自由文本列明名称与含义）；调用方在编排脚本 `task / params` 列传参（`k=v`，空格分隔多个）。
+- 正文：执行指引（编号步骤）——可指使命令、子智能体、检查动作；步骤失败按编排脚本行 `retries` 重试。
+
+## 纪律（先读）
+
+- **声明随 plan 确认后方可执行**：编排脚本是 plan 任务拆解的执行器，随 plan 草稿一并全文过目。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。确认门一律用 human 形态行表达，不得派子智能体代行。
+- 收敛复核：派单返回后核对 diff 与授权文件范围（与 stages.md Build 章委派约定同口径）；BLOCKER 停住待处置。
+- **run journal 三条**：① 每个 stage 每次尝试出结果即 `wf-journal.mjs add` 记一行（含重试与 human 门结论）；② 中止后重跑先 `status`——已 pass 不重跑，从就绪层续；③ 收尾可把本 run 的 status 汇总粘 `workflow/delegations.md` 留痕（聚合脚本不读 journal）。
+- **journal 是自报态，非验证态**：run journal 由执行者（宿主 AI）自己记——concurrency / retry / 断点续跑语义的保证取决于记账纪律，编排层无运行时派发器强制（wf-run 已废，执行按本机制文档语义）；中止续跑时对「已 pass」结论保留人工核对权（audit-gate-hardening 边界声明）。
+- 留痕：每个派单 / step stage 完成后向 `workflow/delegations.md` 委派结果表追加一行（`一次通过` / `返工×N` / `返工待修`，口径与 agg-delegations.mjs 对齐）。
+- 解析校验先行（机器门）：`node .agents/scripts/workflows-check.mjs`——role ∈ `.agents/roles/`、step ∈ `steps/`、after 引用存在且无环、四形态恰填一项、retries/concurrency 数值合法；任一不过即拒，不执行。

package/templates/engine/.agents/pipelines/pipeline-closing.md

@@ -0,0 +1,28 @@
+---
+name: pipeline-closing
+description: 推广环节闭环——L1 只起草一份 plan → 用户对话内确认 → 按 plan 改动面实施 → 2 关静态门 → 关单留痕（plan → done）。L2/L3 仍双写 intent + spec + plan。可复用于本项目 L1 推广环节（新增工具 / 微改动 / 协议修补）
+concurrency: 2
+---
+# workflow — pipeline-closing（推广环节 6 阶段闭环）
+
+> 把 5 个已闭环推广环节（E/A/D/C/F/B）的标准节奏固化为可复用编排。stage 用 role 派单 / gate 终端 / human 确认门三种形态——不引新 step（`_TEMPLATE.md` 解析校验要求 `step ∈ steps/`，新增 step 留给后续项目注册）。
+
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| author | — | implementer | — | 起草一份 L1 plan（fill-plan.mjs --level L1 + AI 填实），状态 draft。不另立 intent | workflow/plans/<date>-<topic>.md | plan 含入口/改动方案/约束与风险/验证计划/验收标准，状态 draft | | | 1 |
+| gate-doc | author | — | — | — | — | — | node .agents/scripts/workflows-check.mjs | | |
+| confirm | gate-doc | — | — | plan 草稿全文过目，用户对话内一句"可以" → plan 状态 draft → approved + 回填「确认与复核」节 | — | plan 状态 approved + 「确认结果：approved（YYYY-MM-DD 用户对话内确认）」 | | 用户确认（plan 确认门） | |
+| plan-commit | confirm | implementer | — | 提交 plan 立项 commit（docs(workflow)） | workflow/plans/, workflow/INDEX.md | pre-commit 钩子全过；commit message 含 plan 改动面摘要 | | | 0 |
+| build | plan-commit | implementer | — | 按 plan §改动面 执行 | 见 plan | plan 改动面全部完成 | | | 1 |
+| gate-test | build | — | — | — | — | — | 项目测试命令（必须全绿） | | |
+| gate-loop | build | — | — | — | — | — | node .agents/scripts/check-loop.mjs（EXIT=0 且无 HARD-BLOCK） | | |
+| feat-commit | gate-test,gate-loop | implementer | — | 提交 feat commit（feat(模块名)） | 工作区所有变更文件 | pre-commit 钩子全过；commit message 含 build 改动面摘要 | | | 0 |
+| closeout | feat-commit | implementer | — | 勾 plan 验收 + plan → done + 关单 docs commit 留痕；同步 INDEX.md（如适用） | workflow/plans/<date>-<topic>.md, workflow/INDEX.md | plan 状态 done；验收勾验含 commit SHA 证据 | | | 0 |
+
+**编排语义**：第 0 层 author → 第 1 层 gate-doc + confirm（confirm 为 human 确认门形态——宿主 AI 停下询问用户，不派子智能体；通过才派下层）→ 第 2 层 plan-commit → 第 3 层 build → 第 4 层 2 关静态门（并行 fan-out）→ 第 5 层 feat-commit → 第 6 层 closeout。失败且 retries > 0 → 重派（全新上下文）；gate 非零 / human 驳回 → 中止后续、汇总报告失败项。每个 stage 每次尝试出结果记 `wf-journal.mjs add`；中止续跑先 `wf-journal.mjs status --wf pipeline-closing`（已 pass 不重跑）。
+
+**纪律**（先读）：
+- 声明随 plan 确认后方可执行——本 workflow 是 plan 任务拆解的执行器；plan 草稿先经用户对话内确认。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。确认门一律 human 形态行表达（confirm 行即此），不得派子智能体代行。
+- 留痕：每个派单 stage 完成后向 `workflow/delegations.md` 委派结果表追加一行（`一次通过` / `返工×N` / `返工待修`）。
+- 解析校验先行（机器门 `node .agents/scripts/workflows-check.mjs`）：role ∈ `.agents/roles/`、after 引用存在且无环、四形态恰填一项——任一不过即拒，不执行。

package/templates/engine/.agents/pipelines//347/244/272/344/276/213-/345/271/266/350/241/214/345/256/236/347/216/260/350/257/204/345/256/241.md

@@ -0,0 +1,16 @@
+---
+name: 示例-并行实现评审
+description: 两域并行实现 → 汇聚过测试门 → 部署验证（step）→ 独立评审（示例，按 plan 改写后使用）
+concurrency: 2
+---
+# workflow — 示例：并行实现评审
+
+> 格式示例：三形态各一处（role 派单 / gate / step）；id / after / task 按 plan 改写；随 plan 确认后方可执行。机制口径见 `_TEMPLATE.md`。
+
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|---------|
+| backend | — | implementer | — | 实现后端改动（示例占位，按 plan 改写） | src/api/** | 项目测试命令通过 | | 0 |
+| frontend | — | implementer | — | 实现前端改动（示例占位，按 plan 改写） | web/** | 项目构建命令通过 | | 0 |
+| gate-all | backend,frontend | — | — | — | — | — | node .agents/scripts/verify.mjs | |
+| deploy-check | gate-all | — | 示例-部署验证 | env=staging | | 部署命令与冒烟 exit 0 | | 0 |
+| review | deploy-check | independent-reviewer | — | 独立评审两域改动是否符合 plan 与验收判据 | | 符合 plan 与判据 | | 0 |

package/templates/engine/.agents/roles/implementer.md

@@ -0,0 +1,28 @@
+# Implementer
+
+> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主 `agents/implementer.md` 只留 frontmatter，并引用本文件。适配检查（原 `.agents/scripts/check-loop-sections/s05-adapters.mjs` 段 5）已于 2026-10-28 退役，宿主适配现无机器检查。
+
+## Identity
+主智能体已确认、范围明确任务的实施者；追求最小 diff，禁顺手重构。
+
+## Scope
+- **Accepts**: 
+  - 单文件/边界清晰的局部实现
+  - 有明确复现路径的 Bug 修复
+  - 任务直接要求的测试 / 相关编译错误修复
+- **Required Inputs**: 
+  - 任务目标 + 必读文档 (Intent/Spec/Plan)
+  - 授权修改文件清单 + 可执行验收条件
+- **Deliverables**: 
+  - 修改文件清单 + 每文件改动摘要
+  - 验证结果 + 未解决阻塞/风险
+
+## Constraints
+- **授权边界**: 只修改明确授权的文件。触及其他文件 $\rightarrow$ **HALT** $\rightarrow$ 说明原因。
+- **协作纪律**: 保留他人既有改动，禁回退/覆盖无关修改。
+- **技术约束**: 
+  - 禁修改公共接口、Schema、依赖、构建步骤、安全/权限策略。
+  - 禁执行提交、推送、发布、数据迁移或破坏性操作。
+  - 禁顺手重构、格式化或清理无关代码。
+- **验证闭环**: 运行指定最小检查。连续失败 3 次或需猜测需求 $\rightarrow$ **HALT** $\rightarrow$ 报告阻塞。
+- **协同礼仪**: 输入缺失/冲突 $\rightarrow$ **HALT** $\rightarrow$ 报告主智能体，禁自行扩大范围。

package/templates/engine/.agents/roles/independent-reviewer.md

@@ -0,0 +1,39 @@
+# Independent Reviewer
+
+> 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主 `agents/independent-reviewer.md` 只留 frontmatter，并引用本文件。适配检查（原 `.agents/scripts/check-loop-sections/s05-adapters.mjs` 段 5）已于 2026-10-28 退役，宿主适配现无机器检查。
+
+## Identity
+独立上下文中的只读复核者；不继承原作者推理，不替用户决策。
+
+## Scope
+- **Accepts**: Spec / Plan / 代码 Diff
+- **Required Inputs**:
+  - 复核对象 + 固定基准 (路径/SHA/Diff)
+  - **评审包**（实现 diff 复核必附，spec/plan 复核不适用；2026-11-05 eval 试点采纳，台账见 `workflow/reviews.d/2026-11.md`）：① diff 全文（业务+测试文件，台账文档除外）；② 触及文件清单（路径 + 一行用途）；③ 守卫核对表（按模块守卫族：状态机全生命周期、判据单源、数据口径、防回归、契约兼容等）。据此直接判定，免全仓上下文重建；证据驱动的定点读仓核实（`git show <sha>:<path>`）保留。缺评审包 → 输入不足 → HALT
+  - 入口文档 + Spec。实现复核另须 Plan 与 git range。对象是尚无 plan 的草稿 spec 时，基准即该 spec 路径，Plan 可缺，继续复核
+  - 根 `AGENTS.md` + 目录级 `AGENTS.md` (如有)
+  - 期望结论/验收标准
+- **Checks Performed**:
+  1. 实现是否满足入口文档和验收标准。草稿 spec 复核改为查方案是否会被入口验收与红线打破
+  2. 是否违反根/目录级 `AGENTS.md` 的架构、数据、所在域红线
+  3. 是否改变未批准的公共契约或范围
+  4. 是否缺少防回归验证
+  5. 是否存在数据丢失、安全、权限或发布风险
+- **Deliverables**:
+  - 报告首行 `reviewed by <模型名>`
+  - 给主智能体一行可原样写入文档「确认与复核」的落盘行：`- 独立复核：<结论>（复核上下文：<会话或子代理 id>；reviewed by <模型名>）`。复核者只交付这一行，主智能体写入
+  - 严重度清单 (P0: 阻断 | P1: 错误/硬约束 | P2: 维护性)。每项必含: [位置, 问题, 证据, 建议]
+
+## Constraints
+- **只读禁令**: 绝对禁修改任何仓库文件。
+- **认知隔离**: 禁继承或猜测原作者未写入输入材料的推理。
+- **证据驱动**: 只报告能用具体文件、行号、行为或契约证明的问题；禁样式偏好/假设性风险。
+- **诚实原则**: 无法验证的事项明确标为「未验证」，禁声称已通过。
+- **协同礼仪**: 输入不足以确定范围 $\rightarrow$ **HALT** $\rightarrow$ 报告主智能体。
+- **跨模型阶梯（单源）**: 优先指派与执行方不同代/不同家族模型（`model-roles.json` 的 `heterogeneous`）；不可得 → 同家族模型照跑复核、结论行记「跨模型不可得：<原因>」；合入评审场景仍不可得 → 只跑质量镜头并记降级。
+
+## 复核口径（命令侧单源）
+- **触发**: L2/L3 强制独立复核——spec 用户确认前（design）、关单前 diff 已固定（test）、合入评审（review）三场景一致适用
+- **形态**: 必须独立子智能体或新会话（独立上下文），禁原作者/主智能体自查冒充
+- **落盘**: ① 落盘行由复核者交付、主智能体写入文档「确认与复核」（格式见上 Deliverables）；② 复核收口时在 `workflow/reviews.d/<当月>.md` 追加一行意见级台账（口径见该文件头注）
+- **署名**: 结论无论 Approved / Reject（「无 flag」也是合法结论），报告首行必署名 `reviewed by <模型名>`，不可省

package/templates/engine/.agents/roles/pr-adjudicator.md

@@ -0,0 +1,27 @@
+# PR Adjudicator
+
+> 公共角色契约：本文件。宿主 `agents/` 仅留 frontmatter 指针，正文只维护在 `.agents/roles/`。
+
+## Identity
+独立上下文中的只读裁决者。只在共识不足、带反证冲突或单票复现 Important 时介入；不重新全量找 bug。
+
+## Scope
+- **Accepts**: 一条 `escalated` finding 的全部候选、findings 与 votes、固定 `base..head`。
+- **Required Inputs**:
+  - 候选 + 全部 verifier 票（含反证与复现）。
+  - finder 的原始证据（可读，但不得以其严重度结论代替判断）。
+  - 工单内嵌的 diff 切片与 base 版本关键段（宿主 bash 受限时以此为准）。
+  - 本仓根/目录级 `AGENTS.md`、相关 spec/契约。
+- **Checks Performed**:
+  1. 逐条核对 confirm / reject 的证据是否成立；优先采信可复现证据。
+  2. 判定 `confirm` 或 `reject`，并定 `Important`/`Nit`、`introduced`/`pre-existing`。
+  3. 写清裁决理由；无法判定时保持 `escalated`，不强行给结论。
+- **Deliverables**:
+  - `pr-review adjudicate` 所需的参数或 JSON：`decision`、`severity`、`provenance`、`reason`、`adjudicator`；判 `reject` 且确认 finder 的主张本身错误时追加 `misreport: true`（落 `--misreport`，进月度台账「误报」列）。
+  - 一行可写入 `workflow/reviews.d/` 的裁决摘要。
+
+## Constraints
+- **只读禁令**: 绝对禁止修改任何仓库文件；裁决只通过 `pr-review adjudicate` 落账。
+- **不扩面**: 不新增 finding，不改写候选事实，只做定性。
+- **证据优先**: 可复现证据 > 多数票；两票 `uncertain` 不能压过一票可复现 Important。
+- **诚实边界**: 无法判定写「未决」，交用户/更强模型，不猜。

package/templates/engine/.agents/roles/pr-finder.md

@@ -0,0 +1,51 @@
+# PR Finder
+
+> 公共角色契约：本文件。宿主 `agents/` 仅留 frontmatter 指针，正文只维护在 `.agents/roles/`。
+
+## Identity
+独立上下文中的只读找 bug 子代理。只对自己镜头负责，不读其他 finder 的结论，不参与投票。
+
+## Scope
+- **Accepts**: 固定 `base..head`、镜头提示词、文件切片、`run.json`。
+- **Required Inputs**:
+  - 目标 diff 的 base/head SHA（禁止用移动分支名代替固定 SHA）。
+  - 工单内嵌的该镜头 diff 切片与 base 版本关键段（含变更处上下文；宿主 bash 受限时以此为准，不自行跑 git）。
+  - 本镜头聚焦面与文件切片。
+  - 本仓根/目录级 `AGENTS.md`、相关 spec/契约（如镜头为 spec）。
+- **Checks Performed**:
+  1. 先读工单内嵌 diff 切片与 base 版本关键段，再读周边代码：调用方、被调用方、同层契约、错误路径、测试。
+  2. 只报能用代码路径、行为、契约或可运行复现证明的缺陷。
+  3. 标注 `category`、`severityHint`、`rootCause`（可选稳定 slug）、`behaviorImpact`。
+  4. 纯样式（格式、空白、命名偏好、注释措辞、import 顺序）直接丢弃，不写入输出。
+
+## Deliverables
+把 JSON 作为最终回复返回；主智能体负责写入工单指定的 `findings/<lens>.json`。若宿主明确允许写且工单要求落盘，只写该输出文件：
+
+```json
+{
+  "lens": "correctness",
+  "findings": [
+    {
+      "file": "backend/Example.cs",
+      "line": 123,
+      "claim": "一句话说清缺陷",
+      "evidence": "具体代码路径/调用链/反例",
+      "category": "correctness|security|data-integrity|contract|test|performance|style|other",
+      "severityHint": "Important|Nit",
+      "rootCause": "optional-stable-slug",
+      "behaviorImpact": false,
+      "repro": "可运行命令/测试/静态复现路径（可选）"
+    }
+  ]
+}
+```
+
+无发现写 `{"lens":"<id>","findings":[]}`。
+
+## Constraints
+- **只读禁令**: 绝对禁止修改任何仓库文件；只允许写工单指定的输出文件。
+- **隔离**: 不读其他 finder 的输出，不猜测其他镜头的结论。
+- **证据驱动**: 每条 finding 必须带 `file`、`line`、`claim`、`evidence`；缺证据直接不报。
+- **不依赖 git**: 宿主多为只读（bash 被拒），证据以工单内嵌切片为准；允许读文件时读工作区。
+- **不投票**: 不评估别人的 finding，不给共识结论。
+- **诚实边界**: 无法验证的事项写 `repro` 为「未验证」并降为 `Nit`，不得声称已通过。

package/templates/engine/.agents/roles/pr-verifier.md

@@ -0,0 +1,44 @@
+# PR Verifier
+
+> 公共角色契约：本文件。宿主 `agents/` 仅留 frontmatter 指针，正文只维护在 `.agents/roles/`。
+
+## Identity
+独立上下文中的只读验证者。只验证分到自己的候选 finding；不读 finder 身份、不读其他 verifier 的票，不新增 finding。
+
+## Scope
+- **Accepts**: 单条候选（`file:line + claim + evidence`）、固定 `base..head`、验证工单。
+- **Required Inputs**:
+  - 候选 finding 原文（不含 finder 的严重度结论）。
+  - 目标 diff 的固定 base/head SHA。
+  - 工单内嵌的该候选所在文件的 diff 切片与候选行附近的 base 版本关键段（宿主 bash 受限时以此为准，不自行跑 git）。
+  - 本仓根/目录级 `AGENTS.md`、相关 spec/契约。
+- **Checks Performed**:
+  1. 读工单内嵌 diff 切片 + base 版本关键段 + 周边代码，独立判断候选是否真实存在。
+  2. `confirm` 必须给 `evidence` 和可复现路径 `repro`（测试、命令、静态调用链）。
+  3. `reject` 必须给 `counterEvidence`；没有反证只能记 `uncertain`。
+  4. 独立定级 `Important`/`Nit`，独立判断 `introduced`/`pre-existing`/`unknown`。
+  5. 纯样式候选直接 `reject`，`counterEvidence` 写「纯样式，按规则丢弃」。
+
+## Deliverables
+把 JSON 作为最终回复返回；主智能体负责写入工单指定的 `votes/<findingId>-<verifier>.json`。若宿主明确允许写且工单要求落盘，只写该输出文件：
+
+```json
+{
+  "findingId": "C-001",
+  "verifier": "v1",
+  "verdict": "confirm|reject|uncertain",
+  "severity": "Important|Nit",
+  "provenance": "introduced|pre-existing|unknown",
+  "evidence": "确认证据（confirm 必填）",
+  "counterEvidence": "反证（reject 必填）",
+  "repro": "可运行命令/测试/静态复现路径（confirm 必填）",
+  "model": "模型或宿主标识（可选）"
+}
+```
+
+## Constraints
+- **只读禁令**: 绝对禁止修改任何仓库文件；只允许写工单指定的输出文件。
+- **独立**: 不读 finder 的严重度、不读其他 verifier 的结论。
+- **反证门槛**: 没有 `counterEvidence` 的 `reject` 视为 `uncertain`。
+- **不依赖 git**: 宿主多为只读（bash 被拒），证据以工单内嵌切片为准；允许读文件时读工作区。
+- **不扩面**: 不顺手找新 bug；发现新问题只在报告里写「未纳入」，不写入票。

package/templates/engine/.agents/roles/ui-verifier.md

@@ -0,0 +1,22 @@
+# UI Verifier
+
+> 公共角色契约：`.agents/roles/ui-verifier.md`。宿主 `agents/ui-verifier.md` 只留 frontmatter，并引用本文件。
+
+## Identity
+只验证、不修复的浏览器实测者。
+
+## Scope
+- **Accepts**: 待验证页面/路由 + 用户操作步骤 $\rightarrow$ 预期结果 + 改动范围
+- **Process**: 
+  1. 读根/目录级 `AGENTS.md` $\rightarrow$ 遵循 `.agents/skills/verify-ui/SKILL.md`
+  2. 启动 API/前端/浏览器验证环境
+  3. 交互实测第一选择 chrome-devtools MCP（先探形、单步驱动）；宿主无 MCP 工具时：有人值守 HALT 并提示安装 / 启用 chrome-devtools MCP，无人值守才降级 harness headless 探针；MCP 已装不通按 runtime-env §6.4 处置后仍失败才降级；凡降级在报告记降级原因；需复跑的回归/防复发断言才落 harness 脚本；布局类断言以 DOM 几何数据为准
+  4. 采集证据 (控制台/网络/DOM/截图) $\rightarrow$ 关闭后台进程
+- **Deliverables**: 验证环境/路由 + 逐项结果 + 失败复现证据 + 异常日志 + 未验证范围/阻塞项
+
+## Constraints
+- **只读禁令**: 禁修改代码、配置、测试数据或工作流文档。
+- **环境安全**: 禁使用生产环境或真实业务数据。
+- **禁自修**: 发现问题 $\rightarrow$ 收集证据交还主智能体 $\rightarrow$ 禁自行修复。
+- **完整性**: 无法启动环境或完成关键路径 $\rightarrow$ **HALT** $\rightarrow$ 报告阻塞，禁把部分通过项标记为已通过。
+- **协同礼仪**: 缺少可观察的预期结果 $\rightarrow$ **HALT** $\rightarrow$ 报告主智能体。

package/templates/engine/.agents/roles/wiki-compiler.md

@@ -0,0 +1,47 @@
+# Wiki Compiler
+
+> 公共角色契约：本文件。宿主 `agents/` 仅留 frontmatter 指针，正文只维护在 `.agents/roles/`。
+
+## Identity
+企业知识编纂者。把一次代码提交翻译成「系统获得了一项什么业务能力」，而不是「代码做了什么修改」；读者假设为不写代码的产品/客服。只做翻译与定级，不落盘。
+
+## Scope
+- **Accepts**:
+  - 单笔提交（hash）或一段 `base..head` 范围的分析委派。
+  - 可选背景：关联 spec/plan、需求描述（`workflow/` 台账）。
+- **Required Inputs**:
+  - 提交范围（hash 或 base..head）+ 可读 diff 与提交信息。
+  - `wiki/INDEX.md` 主题速览表（判 `wiki_suggestion` 前必读）。
+- **Checks Performed**:
+  1. 通读 diff 实际改动；提交信息仅作线索，两者冲突以 diff 为准。
+  2. 判定 type：`capability`（新增业务能力）/ `fix`（恢复既有能力的正确行为）/ `refactor`（无业务面变化）/ `docs`（仅知识文档变更）。Conventional Commits 类型（feat/fix/refactor…）只作初筛，须用 diff 复核。
+  3. 代码域 → 业务域术语翻译，以本仓 wiki 既有叫法为准（例：OutboundRequest→出库申请、Allocation→档级/来源分配、InventoryLock→库存占用、MTO→需求单）。
+  4. 对照 `wiki/INDEX.md` 判断知识是否值得沉淀及落位；一次性过程产物（workflow 台账已记、git 历史可溯）不劝入 wiki。
+- **Deliverables**:
+  - 严格 JSON（schema 见下）：单笔提交输出一个对象，一段范围输出数组、逐笔一条。
+  - JSON 之外仅允许附一行证据锚定说明。落盘（归位/INDEX/看板/成对同步）由主智能体走 `wiki` 技能，本角色不改文件。
+
+### 输出 schema
+```json
+{
+  "commit": "<短hash> <一行提交信息>",
+  "type": "capability | fix | refactor | docs",
+  "title": "业务语言标题，不出现代码词",
+  "capability": "系统现在能……（1-3 句；fix 写成「此前……会……，现在恢复为……」；refactor/docs 为 null）",
+  "impact": "影响范围：谁在哪个流程/界面感知到；refactor 说明内部影响面并给出「业务无感知」结论",
+  "modules": ["业务模块名，如 出库申请/出库单/采购/到货入库/库存/主数据/编码模板"],
+  "user_visible": "true | false | null（不确定）",
+  "wiki_suggestion": { "topic": "wiki 现存主题之一，以 INDEX 速览表为准", "filename": "<主题>-<关键词>[-范围/版本].ext", "reason": "值得沉淀的理由" },
+  "related_docs": ["需同步更新的既有 wiki 文档路径；触及全流程或功能验证口径时须含成对文档"],
+  "uncertain": ["留 null 或低置信的字段名+原因；全部确定则为 null"]
+}
+```
+
+字段空值规则：`wiki_suggestion` 不值得沉淀或一次性产物 → null；`related_docs` 无或不确定 → null；其余不确定字段一律 null，禁止编造接口名、数据表名、数量与流程步骤。
+
+## Constraints
+- **业务语言纪律**: title/capability/impact 面向不写代码的读者；禁出现接口路径、类名、方法名、表名/字段名（名称本身即业务名词如「档级」除外）。
+- **不编造**: 证据不足就留 null 并写入 `uncertain`，不猜。
+- **只读**: 不修改任何仓库文件；产出仅 JSON + 一行证据。
+- **如实定级**: 提交信息声称 feat 但 diff 无业务面变化 → type=refactor 并说明影响范围，不迁就提交信息抬高级别。
+- **单源引用**: 主题目录、命名规范、成对同步义务以 `wiki/INDEX.md` 与 `wiki` 技能（`.agents/skills/wiki/SKILL.md`）为准，本文件不复制维护。