agentic-flow-kit 0.7.0 → 0.9.0

package/templates/_agents/commands/maintain.md

@@ -64,7 +64,7 @@ next: .agents/commands/plan.md(若复盘需要新 intent)
 
 ### 3. 起草后停下
 
-输出草稿全文给用户过目;确认后才执行三件套落地。**确认点不合并**：incident 草稿、spec、plan 各自过目确认（plan 的两道门见 `build.md`）；确认后立即留痕（spec/plan 状态 `approved` + 「确认与复核」节，incident 时间线补「用户确认」条目），`done` 只在关单出现。
+输出草稿全文给用户过目;确认后才执行三件套落地。**确认点不合并**：incident 草稿、spec、plan 各自过目确认（plan 的两道门见 `build.md`）；确认后立即留痕（spec/plan 状态 `approved` + 「确认与复核」节，incident 时间线补「用户确认」条目），`done` 只在关单出现。**L2/L3 机器前置**：起草 spec 时 fill-spec / confirm-doc 校验「时间线含『用户确认』留痕」，未过即拒（exit 2）——被拒回本流程补留痕。
 
 ### 4. 确认后落地
 

package/templates/_agents/commands/new-task.md

@@ -26,11 +26,22 @@ next: 按阶段路由
 | **Maintain** | [.agents/commands/maintain.md](.agents/commands/maintain.md) | "线上出事了" / "记一笔 incident" | `implementer`(方案确认后) | 三件套要点确认 |
 | **Review**(横切,不占 6 阶段) | [.agents/commands/review.md](.agents/commands/review.md) | "评审一下" / "过 review 标准" | `independent-reviewer`(L2/L3 必须独立复核) | 问题定性与合入时机确认 |
 
+## 风险定级(第 0 步,先定级再路由)
+
+动工前先按下表定风险级 L0-L3(就高不就低;判据细则见下节「级别判断」),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
+
+| 泳道 | 级别 | 确认与审计口径 |
+|------|------|---------------|
+| **协作道**(敏捷优先,审计异步补) | L0 例行 / L1 实现级 | L0 直接 commit,豁免 intent;L1 快车道(intent 一句话确认 + 极简 plan)即动工。独立复核不设同步前置,check-loop 与事后 review 兜底;确认/代录可 `--batch` 批量(仅 L0/L1) |
+| **防御道**(严谨优先,确认同步拦) | L2 规则/契约 / L3 数据与运行时结构 | 同步确认门:spec 确认通过方可起草 plan,plan 确认后方可动手;L3 加新会话独立复核,未确认不放行 |
+
+> 定级结果落 intent frontmatter `risk_level`(=级别,`fill-intent.mjs` 自动写入,机器选道用);协作道勾触达红线会被 check-loop 判「红线判低」hard 拦(就高升级 L2/L3 并补同名 spec)。
+
 ## 路由判断
 
 - **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
 - **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
- - L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 plan → `test.md`
+  - L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 Quick-Plan → `test.md`
  - L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
  - 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
 - **改完代码要验证**:直接进 `test.md`（验证通过即关单；L1 到此结束）
@@ -42,7 +53,7 @@ next: 按阶段路由
 | 级别 | 改什么 | 流程 |
 |------|--------|------|
 | L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
-| L1 | **实现级改动**(未命中 L2/L3) | 轻量入口文档(intent / incident) + plan |
+| L1 | **实现级改动**(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) $\rightarrow$ 实现 $\rightarrow$ 一键固化(`solidify-task.mjs`) |
 | L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
 | L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
 

package/templates/_agents/commands/plan.md

@@ -7,7 +7,7 @@ triggers:
   - "新需求 <主题>"
   - "要做个 <功能>"
 approval_required: true
-next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
+next: L1 → .agents/commands/build.md (起草 Quick-Plan) ；L2/L3 → .agents/commands/design.md
 ---
 
 # Plan · 立 intent
@@ -21,7 +21,7 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
 2. 否则起草新 intent:
    - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收，新 intent 引用（防重复立项 / 重复踩坑）
-   - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 5 字段 + 7 节正文（背景与问题/目标/非目标/约束/影响面/触达红线/验收标准）的草稿；AI 据此填实，模板与节标题机器保证不出错
+   - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段（含 risk_level）+ 7 节正文（背景与问题/目标/非目标/约束/影响面/触达红线/验收标准）的草稿；AI 据此填实，模板与节标题机器保证不出错
    - 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
    - frontmatter 填 `模块:`（词表见 `.agents/workflow-modules.txt`，新建文档必填，check-loop 会警告）
    - 按 6 节填写:背景与问题 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线（L1 微改动可省非目标/约束两节，不硬填）
@@ -29,7 +29,7 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
 4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
 
-   **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
+   **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
 
 ## 技能辅助(可选,宿主级 skills)
 
@@ -45,5 +45,5 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 ## 确认后
 
 - intent 状态 draft → approved
-- 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
+- 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)——**提交最早可行点**：入口文档受 pre-commit 闭环配对（增量）门约束，同名 spec / plan 须已在工作区（先例 61ec130）
 - L1 → `.agents/commands/build.md`；L2/L3 → `.agents/commands/design.md`

package/templates/_agents/commands/review.md

@@ -43,7 +43,7 @@ next: .agents/commands/build.md（仅 P0 / P1 未清时；清零后经用户确
 - **Create/Update 校验同口径**：Create 已有校验 Update 必须同口径；被引用的标识符字段禁改
 - **查询分页与状态语义**：分页参数范围校验 + 服务层钳制；非法状态与不存在分离(按项目统一错误口径,如 400 / 404)
 - **spec 承诺的断言落地**：spec §测试列出的用例 / 断言须真落到测试或验证脚本；「写进 spec」不等于「跑得起来」，且常驻断言禁写成随时间增长的行数常量
-- **跨宿主薄适配正文漂移**：改 `templates/_agents/{commands,roles}/*.md` 后必须跑 `flow-kit sync-hosts --apply` 单向同步 4 宿主薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）；装户视角由 `flow-kit doctor` §6.7 检查（包源环境 §6.7 skipped）
+- **跨宿主薄适配正文漂移**：改 `templates/_agents/{commands,roles}/*.md` 后必须跑 `flow-kit sync-hosts --apply` 单向同步注册表内全部宿主薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）；装户视角由 `flow-kit doctor` §6.7 检查（包源环境 §6.7 skipped）
 
 ## P2 建议（提醒，不拦合入）
 

package/templates/_agents/commands/source-sync-check.md

@@ -76,7 +76,7 @@ flow-kit doctor                                     # 10/0/0
 - 不改 managed 台账跟踪逻辑（`sync.mjs` 不动）
 - 不改 owned 漂移校验（`doctor.mjs` §6.6 不动）
 - 不反向同步——装副本独自有文件（如 hooks/commit-check.config.json）可能是装户配置，不应被删
-- 不检查 4 宿主 `modules/hosts/` 薄适配漂移（那是 `flow-kit sync-hosts` 范围）
+- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移（那是 `flow-kit sync-hosts` 范围）
 
 ## 当前已识别的真实漂点（首次实测，2026-09-25）
 

package/templates/_agents/commands/sync-hosts.md

@@ -17,7 +17,7 @@ next: .agents/commands/build.md（漂移属 build 改权威源未同步导致的
 
 # Sync-Hosts · 跨宿主适配层正文段同步
 
-> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（trae commands 加 `name: wf-X`、opencode/zcode/omp 各自原描述）。
+> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
 > 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
 
 ## 何时跑

package/templates/_agents/commands/test.md

@@ -74,10 +74,12 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
   - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
-  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」，intent → done；同名 spec（若有）仍 approved → done
-**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
+  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
+  - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
   - 修复：防复发验证已落地，incident → closed（经确认门 confirm-doc：open→fixed / fixed→closed 两跳、无单跳；2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认，口径同 done 内容绑定）
   - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
   - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）
+  - **委派快照回写**：关单后若 `workflow/delegations.md` §月度聚合快照缺当月行或 doctor §6.5 报陈旧 → 跑 `node .agents/scripts/agg-delegations.cjs` 并回贴当月快照行
 - L1：本阶段结束，不进 deploy
 - L2/L3：仅当用户确认要上 prod 时进 `.agents/commands/deploy.md`

package/templates/_agents/hooks/commit-check.cjs

@@ -1,7 +1,7 @@
 // commit-check: git commit 前置验证（agentic-flow-kit 通用版）
 // 1) 敏感信息扫描（暂存区新增行含疑似密钥 -> BLOCK）
-// 2) 条件构建验证（按 .agents/hooks/commit-check.config.json 的 builds 配置；--full 全跑）
-// 3) 质量检测（config.checks：lint / 类型检查 / vet 等秒级确定性检查；--full 全跑）
+// 2) 条件构建验证（按 .agents/hooks/commit-check.config.json 的 builds 配置；--full 不做 ext/prefix 裁剪，仍尊重 when）
+// 3) 质量检测（config.checks：lint / 类型检查 / vet 等秒级确定性检查；--full 不做 ext/prefix 裁剪，仍尊重 when）
 // config 由 flow-kit init 按技术栈生成初值，项目可自行增改；缺失或无 builds/checks 时跳过对应段。
 // 配置示例（.agents/hooks/commit-check.config.json）：
 //   {
@@ -23,8 +23,11 @@
 //   - 只有 ext：按扩展名全局触发（跨目录，适合语言型触发——仓库里该扩展名基本只属于该构建）；
 //   - 只有 prefix：该前缀下任何文件触发（目录型触发——如 monorepo 子包，仓库其他位置的相同扩展名不触发）；
 //   - 两者同配为 OR 并集而非 AND 交集——要「前缀内的特定扩展名」请只配 prefix（目录内文档变更多跑一次构建，方向安全）。
-// checks.when：路径数组，任一存在才启用（元素支持尾部 * 一层通配，如 "*.sln"）——
-//   没有对应配置的项目自动跳过并提示，不 fail-closed 误拦；无 when 字段 = 无条件启用。
+// when（builds 与 checks 共用）：数组任一满足才启用，无 when 字段 = 无条件启用。
+//   - 路径或尾部 * 一层通配（如 "*.sln"）：相对仓库根做存在性判断；
+//   - pkg:<点分路径>（如 pkg:scripts.build）：读该项 cwd（缺省仓库根）的 package.json，
+//     沿路径取值，非空字符串才算满足。
+//   没有对应配置的项目自动跳过并提示，不 fail-closed 误拦。--full 同样尊重 when。
 const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
@@ -78,17 +81,50 @@ if (hits.length) {
 
 // --- 2) 条件构建验证 ---
 // --full：合并提交（pre-merge-commit / 冲突解决后手动 commit）使用——合并结果是没人验证过的新状态，
-// 按 ext/prefix 裁剪可能漏掉需要重跑的一侧，故不做条件选择、全部 builds 都跑。
+// 按 ext/prefix 裁剪可能漏掉需要重跑的一侧，故不做路径裁剪。when 仍生效：没有对应能力就不跑。
 // 引擎自身文件（.agents/、.githooks/）不参与构建匹配——工作流引擎不是项目构建产物。
 const FULL = process.argv.includes('--full');
 const stagedForBuild = staged.filter(f => !f.startsWith('.agents/') && !f.startsWith('.githooks/'));
-let ranAny = false;
+
+// whenSatisfied：任一谓词满足即启用。pkg: 读 cwd 下的 package.json；其余谓词相对仓库根。
+function whenItem(w, cwd) {
+  if (typeof w === 'string' && w.startsWith('pkg:')) {
+    const keys = w.slice(4).split('.').filter(Boolean);
+    if (!keys.length) return false;
+    const pkgPath = path.join(cwd || '.', 'package.json');
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch (e) { return false; }
+    let cur = pkg;
+    for (const k of keys) {
+      if (cur == null || typeof cur !== 'object' || !Object.prototype.hasOwnProperty.call(cur, k)) return false;
+      cur = cur[k];
+    }
+    return typeof cur === 'string' && cur.trim() !== '';
+  }
+  const star = String(w).indexOf('*');
+  if (star < 0) return fs.existsSync(w);
+  const suffix = w.slice(star + 1);
+  const dir = path.dirname(w.slice(0, star)) || '.';
+  try { return fs.readdirSync(dir).some((f) => f.endsWith(suffix)); } catch (e) { return false; }
+}
+function whenSatisfied(when, cwd) {
+  if (!when) return true;
+  const list = Array.isArray(when) ? when : [when];
+  return list.some((w) => whenItem(w, cwd));
+}
+function skipWhen(kind, item) {
+  const shown = Array.isArray(item.when) ? item.when.join(' / ') : item.when;
+  console.log(`SKIP: ${item.name}（未找到 ${shown}，跳过${kind}——配置好后自动启用）`);
+}
+
+let consideredBuild = false;
 for (const b of (config.builds || [])) {
   if (!b || !b.command) continue;
   const exts = Array.isArray(b.ext) ? b.ext : [];
   const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (b.prefix ? f.startsWith(b.prefix) : false));
   if (!match) continue;
-  ranAny = true;
+  consideredBuild = true;
+  if (!whenSatisfied(b.when, b.cwd)) { skipWhen('构建', b); continue; }
   const r = sh(b.command, b.cwd);
   if (!r.ok) {
     if (b.lockPattern && new RegExp(b.lockPattern).test(r.out)) {
@@ -101,25 +137,13 @@ for (const b of (config.builds || [])) {
   }
   console.log(`OK: ${b.name} 构建通过（${b.command}）`);
 }
-if (!ranAny) {
+if (!consideredBuild) {
   console.log(config.builds && config.builds.length
     ? 'SKIP: 无匹配的源码变更，跳过构建验证'
     : 'SKIP: 未配置 builds（.agents/hooks/commit-check.config.json），跳过构建验证');
 }
 
 // --- 3) 质量检测（checks：lint / 类型检查 / vet 等秒级确定性检查；测试不放这里——关单在 test.md 阶段门） ---
-// whenSatisfied：任一路径存在即启用；元素支持尾部 * 一层通配（如 *.sln = 仓库根存在 .sln 结尾文件）
-function whenSatisfied(when) {
-  if (!when) return true;
-  const list = Array.isArray(when) ? when : [when];
-  return list.some((w) => {
-    const star = w.indexOf('*');
-    if (star < 0) return fs.existsSync(w);
-    const suffix = w.slice(star + 1);
-    const dir = path.dirname(w.slice(0, star)) || '.';
-    try { return fs.readdirSync(dir).some((f) => f.endsWith(suffix)); } catch (e) { return false; }
-  });
-}
 let ranCheck = false;
 for (const c of (config.checks || [])) {
   if (!c || !c.command) continue;
@@ -127,10 +151,7 @@ for (const c of (config.checks || [])) {
   const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (c.prefix ? f.startsWith(c.prefix) : false));
   if (!match) continue;
   ranCheck = true;
-  if (!whenSatisfied(c.when)) {
-    console.log(`SKIP: ${c.name}（未找到 ${Array.isArray(c.when) ? c.when.join(' / ') : c.when}，跳过质量检查——配置好后自动启用）`);
-    continue;
-  }
+  if (!whenSatisfied(c.when, c.cwd)) { skipWhen('质量检查', c); continue; }
   const r = sh(c.command, c.cwd);
   if (!r.ok) {
     console.log(`BLOCK: ${c.name} 质量检查未通过（${c.command}）\n` + r.out.slice(0, 1200));

package/templates/_agents/lane-surfaces.txt

@@ -0,0 +1,14 @@
+# L2 触达面清单（单源：本文件——check-lane-surface.mjs 检查 A 共读，pre-commit「泳道完整性」门禁）
+# 格式：每行一条 ERE（grep -E 兼容），匹配暂存文件的仓库相对路径（/ 分隔）。
+#   # 注释与空行忽略；本文件缺失或清单为空 = 检查跳过（装户无感升级）。
+#   正则语法错误行 → 门禁 fail-closed 阻断（防静默空洞，修配置后重试）。
+# 语义：命中任一模式 = 本次改动触及「一处定义、多处消费」的契约 / 规则面（L2 触达面，
+#   判据见 .agents/commands/new-task.md §级别判断）。此时须有活跃（draft/approved / open/fixed）
+#   L2/L3 入口罩着；活跃入口全为 L0/L1 会被 pre-commit「触达面判低」拦截（三选修法见门禁消息）。
+#   无任何活跃入口时仅 advisory——docs / bootstrap 豁免类改动（new-task.md §intent 豁免）不受阻。
+# 本仓默认面（引擎 / 契约面，行为承载目录——commands/roles 纯提示文本属 docs 级不列入；按项目自行改）：
+^templates/
+^\.agents/(scripts|hooks)/
+^\.githooks/
+^bin/
+^modules/

package/templates/_agents/roles/implementer.md

@@ -1,6 +1,6 @@
 # Implementer
 
-> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（各宿主目录下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
 
 ## 职责
 

package/templates/_agents/roles/independent-reviewer.md

@@ -1,6 +1,6 @@
 # Independent Reviewer
 
-> 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/independent-reviewer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+> 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主薄适配（各宿主目录下 `agents/independent-reviewer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
 
 ## 职责
 

package/templates/_agents/roles/ui-verifier.md

@@ -1,6 +1,6 @@
 # UI Verifier
 
-> 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+> 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（各宿主目录下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
 
 ## 职责
 

package/templates/_agents/scripts/check-lane-surface.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// check-lane-surface.mjs — 泳道完整性门禁（pre-commit 增量；2026-10-01 drift-hardening）
+// 检查 A「触达面判低」：暂存 diff 命中项目 L2 触达面（.agents/lane-surfaces.txt，ERE 逐行；
+//   # 注释与空行忽略；文件缺失或清单为空 = 检查跳过，装户无感）时——
+//   存在活跃 L2/L3 入口 → 放行（归因歧义为已知边界：机器不猜「哪个入口在干这批改动」）；
+//   活跃入口全为 L0/L1（含级别缺失）→ hard 拦，点名最新 L0/L1 入口 + 三选修法；
+//   无任何活跃入口 → 仅 advisory（docs / bootstrap 豁免类改动的合法形态）。
+//   活跃 = intents draft/approved + incidents open/fixed（incident≡intent 等价口径）。
+//   experiment/* 分支降级 advisory（泳道哲学：PoC 免闭环纪律，转正由 pre-push 加固门兜底）。
+// 检查 B「探索标记缺失」：experiment/* 分支暂存的 workflow/intents/*.md（排除 _TEMPLATE）
+//   frontmatter 无「阶段: exploring」且无「状态: exploring」（口径同 check-loop 加固门）→ hard 拦。
+//   标记是加固门覆盖率的前提且补写零成本——advisory 免的是纪律负担，不免标记本身。
+// 判据原则（incidents/2026-09-28-batch-ledger-audit 教训）：只用一手事实——暂存文件清单、
+//   当前分支名、工作区 frontmatter 字段；不用时间戳 / 字符串相等反推过程事实。
+// 边界：git 调用一律 -c core.quotepath=off（非 ASCII 路径教训，同 check-pairing-incremental.sh）；
+//   frontmatter 读取容忍 CRLF（显式按 \r?\n 切分）；detached HEAD 分支不可判 → A 按 strict、
+//   B 跳过（沿 pairing 门先例）；配置行正则语法错误 → fail-closed（防静默空洞）。
+// 已知边界：commit-time 门禁，CI / pre-push 复跑面无对应全量检查（push 时刻无暂存 diff 一手事实，
+//   树级反推违背判据原则）——沿增量门禁 pre-commit-only 先例，声明于 spec 风险评估 R2。
+// 用法：node check-lane-surface.mjs [--root <dir>] [--branch <名>] [--staged-file <清单文件>]
+//   （--root/--branch/--staged-file 为测试注入位；缺省自 git 发现。staged-file 每行一个仓库相对路径）
+// 退出码：0 放行（含 advisory）；1 阻断（stderr 出 [标签] 消息与修法）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+
+const gitOut = (cwd, gitArgs) => {
+  const r = spawnSync('git', ['-c', 'core.quotepath=off', ...gitArgs], { cwd, encoding: 'utf8' });
+  return r.status === 0 ? String(r.stdout || '') : '';
+};
+
+const ROOT = argOf('--root') || gitOut(process.cwd(), ['rev-parse', '--show-toplevel']).trim() || process.cwd();
+// detached HEAD 时 abbrev-ref 返回 'HEAD' → 不匹配 experiment/* → A strict / B 跳过
+const BRANCH = argOf('--branch') || gitOut(ROOT, ['rev-parse', '--abbrev-ref', 'HEAD']).trim();
+const stagedArg = argOf('--staged-file');
+const STAGED = stagedArg
+  ? fs.readFileSync(stagedArg, 'utf8').split(/\r?\n/).filter(Boolean)
+  : gitOut(ROOT, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']).split(/\r?\n/).filter(Boolean);
+
+const isExperiment = /^experiment\//.test(BRANCH);
+
+// frontmatter 读取（CRLF 容忍；口径同 check-loop fmGet：--- 包夹、键行前缀匹配）
+const fmOf = (file) => {
+  const fm = {};
+  let lines;
+  try {
+    lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  } catch {
+    return fm;
+  }
+  if (!/^---\s*$/.test(lines[0] || '')) return fm;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) break;
+    const m = lines[i].match(/^([^:]+):\s*(.*)$/);
+    if (m) fm[m[1].trim()] = m[2].trim();
+  }
+  return fm;
+};
+
+// 触达面配置：缺失/空 → []（检查 A 跳过）；语法错误 → fail-closed
+const loadPatterns = () => {
+  const file = path.join(ROOT, '.agents', 'lane-surfaces.txt');
+  if (!fs.existsSync(file)) return [];
+  const bad = [];
+  const pats = fs.readFileSync(file, 'utf8')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'))
+    .map((l) => {
+      try {
+        return new RegExp(l);
+      } catch {
+        bad.push(l);
+        return null;
+      }
+    })
+    .filter(Boolean);
+  if (bad.length) {
+    console.error(`泳道完整性（增量）— BLOCK:\n  [面清单语法错误] .agents/lane-surfaces.txt 存在非法 ERE 行：${bad.join(' | ')}\n  修法：修正或删除该行后重试（fail-closed，防静默空洞）`);
+    process.exit(1);
+  }
+  return pats;
+};
+
+// 活跃入口收集（incident≡intent 等价；日期键 intent=日期 / incident=发现）
+const ACTIVE = {
+  intent: new Set(['draft', 'approved']),
+  incident: new Set(['open', 'fixed']),
+};
+const collectActive = () => {
+  const out = [];
+  for (const [dir, kind, dateKey] of [['intents', 'intent', '日期'], ['incidents', 'incident', '发现']]) {
+    const dirPath = path.join(ROOT, 'workflow', dir);
+    if (!fs.existsSync(dirPath)) continue;
+    for (const f of fs.readdirSync(dirPath).sort()) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const fm = fmOf(path.join(dirPath, f));
+      if (!ACTIVE[kind].has(fm['状态'] || '')) continue;
+      out.push({ rel: `workflow/${dir}/${f}`, base: f.replace(/\.md$/, ''), level: fm['级别'] || '', date: fm[dateKey] || '', kind });
+    }
+  }
+  return out;
+};
+
+const blocks = [];
+const advisories = [];
+
+// --- 检查 A：触达面判低 ---
+const patterns = loadPatterns();
+const hits = patterns.length ? STAGED.filter((p) => patterns.some((re) => re.test(p))) : [];
+if (hits.length) {
+  const active = collectActive();
+  const hasHigh = active.some((e) => e.level === 'L2' || e.level === 'L3');
+  if (!hasHigh) {
+    const low = active.filter((e) => e.level !== 'L2' && e.level !== 'L3');
+    if (low.length) {
+      const newest = [...low].sort((a, b) => (b.date || '').localeCompare(a.date || '') || b.rel.localeCompare(a.rel))[0];
+      const text = [
+        `[触达面判低] 暂存命中 L2 触达面，但活跃入口全为 L0/L1（含级别缺失）：`,
+        `  命中: ${hits.join(' ')}`,
+        `  关联入口: ${newest.rel}（${newest.level || '级别缺失'}${newest.date ? `，${newest.date}` : ''}；活跃 L0/L1 共 ${low.length} 件）`,
+        `  修法（三选一）: ① 升级该入口「级别/risk_level」至 L2/L3 并补同名 spec（.agents/commands/design.md）`,
+        `    ② 该入口已完成则关单（done）或显式放弃（superseded/cancelled）——不留活跃残留`,
+        `    ③ 面清单误配则修 .agents/lane-surfaces.txt`,
+      ].join('\n');
+      if (isExperiment) advisories.push(`（advisory·experiment 泳道，不阻断；转正由 pre-push 加固门兜底）\n${text}`);
+      else blocks.push(text);
+    } else {
+      advisories.push(`[触达面判低]（advisory）暂存命中 L2 触达面（${hits.length} 个文件），但当前无任何活跃入口——若非 docs / bootstrap 豁免类改动（.agents/commands/new-task.md §intent 豁免），请先立入口文档`);
+    }
+  }
+}
+
+// --- 检查 B：探索标记缺失（仅 experiment/* 分支）---
+if (isExperiment) {
+  const missing = STAGED
+    .filter((p) => /^workflow\/intents\/[^/]+\.md$/.test(p) && path.basename(p) !== '_TEMPLATE.md')
+    .filter((p) => {
+      const fm = fmOf(path.join(ROOT, p));
+      return fm['阶段'] !== 'exploring' && fm['状态'] !== 'exploring';
+    });
+  if (missing.length) {
+    blocks.push([
+      `[探索标记缺失] experiment/* 分支暂存的 intent 缺「阶段: exploring」标记：`,
+      ...missing.map((p) => `  ${p}`),
+      `  修法（二选一）: ① frontmatter 补一行「阶段: exploring」（advisory 免纪律不免标记——标记是 pre-push 加固门覆盖率的前提）`,
+      `    ② 该件不属探索——换正式分支走标准泳道`,
+    ].join('\n'));
+  }
+}
+
+for (const a of advisories) console.error(`泳道完整性（增量）— advisory:\n${a}\n`);
+if (blocks.length) {
+  for (const b of blocks) console.error(`泳道完整性（增量）— BLOCK:\n${b}\n`);
+  console.error('pre-commit: 泳道完整性未通过，提交已阻止（spec: workflow/specs/2026-10-01-drift-hardening.md）');
+  process.exit(1);
+}
+process.exit(0);