agentic-flow-kit 1.7.15 → 1.8.0

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

@@ -8,7 +8,7 @@
 // 检查 A「触达面判低」：暂存 diff 命中项目 L2 触达面（.agents/lane-surfaces.txt，ERE 逐行；
 //   # 注释与空行忽略；文件缺失或清单为空 = 检查跳过，装户无感）时——
 //   存在活跃 L2/L3 入口 → 放行（归因歧义为已知边界：机器不猜「哪个入口在干这批改动」）；
-//   活跃入口全为 L0/L1（含级别缺失）→ hard 拦，点名最新 L0/L1 入口 + 三选修法；
+//   活跃入口全为 L1（含级别缺失）→ hard 拦，点名最新 L1 入口 + 三选修法（2026-10-13 L0 退役，低泳道=L1 专属）；
 //   无任何活跃入口 → 仅 advisory（docs / bootstrap 豁免类改动的合法形态）。
 //   活跃 = intents draft/approved + incidents open/fixed（incident≡intent 等价口径）。
 //   experiment/* 分支降级 advisory（泳道哲学：PoC 免闭环纪律，转正由 pre-push 加固门兜底）。
@@ -17,7 +17,7 @@
 //   标记是加固门覆盖率的前提且补写零成本——advisory 免的是纪律负担，不免标记本身。
 // 判据原则（2026-09-28 台账批量代录事故教训）：只用一手事实——暂存文件清单、
 //   当前分支名、工作区 frontmatter 字段；不用时间戳 / 字符串相等反推过程事实。
-// 边界：git 调用一律 -c core.quotepath=off（非 ASCII 路径教训，同 check-pairing-incremental.sh）；
+// 边界：git 调用一律 -c core.quotepath=off（非 ASCII 路径教训，同 check-pairing-incremental.mjs）；
 //   frontmatter 读取容忍 CRLF（显式按 \r?\n 切分）；detached HEAD 分支不可判 → A 按 strict、
 //   B 跳过（沿 pairing 门先例）；配置行正则语法错误 → fail-closed（防静默空洞）。
 // 已知边界：commit-time 门禁，CI / pre-push 复跑面无对应全量检查（push 时刻无暂存 diff 一手事实，
@@ -30,6 +30,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { laneOfEntry, laneOfDoc } from './stage-gates.mjs';
 import { loadKitPolicy } from './policy.mjs';
+import { loadLevelHints, hintLevelFor, rankOf, maxLevel } from './level-criteria.mjs';
 
 const argv = process.argv.slice(2);
 const argOf = (k) => {
@@ -126,32 +127,80 @@ const collectActive = () => {
 const blocks = [];
 const advisories = [];
 
+// --- 检查 A0：level-hints 路径下限对账（2026-10-13 hints-backstop）----------------
+// 背景：此前「就高不就低」只在 flow-kit route 输出 advisory，而提交面判低门只认 lane-surfaces.txt
+//   → 两份清单各管一头、**无机器对账**：项目在 hints 里登记了「改这些面至少 L2/L3」，提交面却可能
+//   靠一个 L1 活跃入口放行（判低有机可乘）。本段把 hints 接进提交面：
+//   ① hints 命中 → 要求存在**级别 ≥ 命中档**的活跃入口（不只「有个 high 入口」），否则 hard 拦；
+//   ② hints 已登记高风险面、lane-surfaces.txt 却缺失/为空 → advisory 提示「意图面登记了、提交面无兜底」。
+//   fail-closed：hints 语法错 → hard 拦（写错配置比没配置危险，见 level-criteria parseLevelHints）。
+const hintsState = (() => {
+  try {
+    const { hints } = loadLevelHints(ROOT);
+    return { hints, invalid: null };
+  } catch (e) {
+    return { hints: [], invalid: e.message };
+  }
+})();
+
+if (hintsState.invalid) {
+  blocks.push([
+    '[level-hints 配置错误] .agents/level-hints.txt 非法（档位只收 L2/L3；ERE 不得带行内注释）——配置面坏了整条兜底不可信：',
+    ...String(hintsState.invalid).split('\n').map((l) => `  ${l}`),
+    '  修法：修正清单后重试（fail-closed，防静默空洞——写错配置比没配置危险：没配置会提示，写错会误判档位）',
+  ].join('\n'));
+}
+
+// 命中判定复用判据单源的 hintLevelFor（2026-10-13 executor-review）：此前本文件手写了一遍
+//   「路径归一化 + 多条命中取高档」，与 level-criteria.mjs:104 的实现同形但独立演进——
+//   双源漂移是本仓硬规则（doctor 段就写着「不复刻解析器」），一旦归一化口径调整，
+//   route 会判 L1 而本门拦 L3，且没有任何测试能发现。
+const hintHits = hintsState.hints.length
+  ? STAGED
+    .map((p) => ({ p, lv: hintLevelFor(hintsState.hints, [p]).level }))
+    .filter((x) => x.lv)
+  : [];
+const hintLevel = hintHits.reduce((acc, x) => maxLevel(acc, x.lv), '');
+
 // --- 检查 A：触达面判低 ---
 const patterns = loadPatterns();
+
+if (hintLevel && !patterns.length) {
+  advisories.push(
+    `[level-hints 无提交面兜底] .agents/level-hints.txt 登记了 ${hintHits.length} 个命中（${hintHits.slice(0, 5).map((x) => `${x.p}→${x.lv}`).join(' ')}）——`
+    + '但 .agents/lane-surfaces.txt 缺失或为空，触达面判低检查整体跳过：意图面登记了高风险面，提交面却无兜底',
+  );
+}
 const hits = patterns.length ? STAGED.filter((p) => patterns.some((re) => re.test(p))) : [];
-if (hits.length) {
+// 本次提交触达到的**最低应然档位**：lane-surfaces 命中隐含 L2（沿原口径），hints 命中按登记档取。
+// 混档取高——与 level-criteria maxLevel 同一口径（就高不就低在提交面同样成立）。
+const requiredLevel = maxLevel(hits.length ? 'L2' : '', hintLevel);
+if (requiredLevel) {
   const active = collectActive();
-  const hasHigh = active.some((e) => e.lane === 'high');
-  if (!hasHigh) {
-    const low = active.filter((e) => e.lane !== 'high'); // low + suspect 均拦（suspect 不作豁免依据）
-    if (low.length) {
-      const newest = [...low].sort((a, b) => (b.date || '').localeCompare(a.date || '') || b.rel.localeCompare(a.rel))[0];
-      const fixVerb = newest.lane === 'suspect'
-        ? '① 对齐该入口「级别」与「risk_level」两字段至一致的 L2/L3（fill-intent 双写口径；现两值缺失/非法/分歧）并补同名 spec（.agents/commands/design.md）'
-        : '① 升级该入口「级别」与「risk_level」两字段至 L2/L3 并补同名 spec（.agents/commands/design.md）';
-      const text = [
-        `[触达面判低] 暂存命中 L2 触达面，但活跃入口无泳道 high（存在 low/suspect）：`,
-        `  命中: ${hits.join(' ')}`,
-        `  关联入口: ${newest.rel}（级别 ${newest.level || '缺失'}/risk_level ${newest.risk || '缺失'}→ 泳道 ${newest.lane}${newest.date ? `，${newest.date}` : ''}；活跃非 high 共 ${low.length} 件）`,
-        `  修法（三选一）: ${fixVerb}`,
-        `    ② 该入口已完成则关单（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 豁免），请先立入口文档`);
-    }
+  const requiredRank = rankOf(requiredLevel) ?? 1;
+  // 入口是否够格：级别 rank ≥ 应然档。**suspect（级别/risk_level 缺失、非法或分歧）一律不够格**——
+  //   沿用原口径「suspect 不作豁免依据」：分歧（L2/L1）这类看似够档的入口，机器无法确认它真罩着这批改动。
+  const enough = (e) => e.lane !== 'suspect' && (rankOf(e.level) ?? -1) >= requiredRank;
+  const insufficient = active.filter((e) => !enough(e));
+  if (insufficient.length) {
+    const newest = [...insufficient].sort((a, b) => (b.date || '').localeCompare(a.date || '') || b.rel.localeCompare(a.rel))[0];
+    const hitList = [...hits.map((p) => `${p}（触达面）`), ...hintHits.map((x) => `${x.p}（hints→${x.lv}）`)];
+    const fixVerb = newest.lane === 'suspect'
+      ? `① 对齐该入口「级别」与「risk_level」两字段至一致的 ${requiredLevel}（fill-intent 双写口径；现两值缺失/非法/分歧）并补同名 spec（.agents/commands/design.md）`
+      : `① 升级该入口「级别」与「risk_level」两字段至 ${requiredLevel} 及以上并补同名 spec（.agents/commands/design.md）`;
+    const text = [
+      `[触达面判低] 暂存命中高风险面，但活跃入口无 ${requiredLevel} 及以上（存在更低档/low/suspect）：`,
+      `  命中: ${hitList.join(' ')}`,
+      `  关联入口: ${newest.rel}（级别 ${newest.level || '缺失'}/risk_level ${newest.risk || '缺失'}→ 泳道 ${newest.lane}${newest.date ? `，${newest.date}` : ''}；活跃不足共 ${insufficient.length} 件）`,
+      ...(hintLevel ? ['  判据：.agents/level-hints.txt 登记的路径下限——就高不就低在提交面同样成立（此前只 advisory，无门）'] : []),
+      `  修法（三选一）: ${fixVerb}`,
+      `    ② 该入口已完成则关单（done）或显式放弃（superseded/cancelled）——不留活跃残留`,
+      `    ③ 清单误配则修 .agents/lane-surfaces.txt${hintLevel ? ' 或 .agents/level-hints.txt' : ''}`,
+    ].join('\n');
+    if (isExperiment) advisories.push(`（advisory·experiment 泳道，不阻断；转正由 pre-push 加固门兜底）\n${text}`);
+    else blocks.push(text);
+  } else if (!active.length) {
+    advisories.push(`[触达面判低]（advisory）暂存命中高风险面（${hits.length + hintHits.length} 个文件，应然 ${requiredLevel}），但当前无任何活跃入口——若非 docs / bootstrap 豁免类改动（.agents/commands/new-task.md §intent 豁免），请先立入口文档`);
   }
 }
 
@@ -176,7 +225,7 @@ if (isExperiment) {
 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: 泳道完整性未通过，提交已阻止（判据见 .agents/commands/new-task.md §级别判断）');
+  console.error('pre-commit: 泳道完整性未通过，提交已阻止（判据单源见 .agents/scripts/level-criteria.mjs）');
   process.exit(1);
 }
 process.exit(0);

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

@@ -44,7 +44,7 @@ const base = (root, { level = 'L1', status = 'approved', extra = null } = {}) =>
   w(root, 'workflow/intents/2026-09-28-old-l1.md', intent('x', `状态: ${status}\n级别: ${level}\n日期: 2026-09-28\n模块: pipeline`));
   if (extra) w(root, extra[0], intent('y', extra[1]));
 };
-const FM_L0_NEW = '状态: draft\n级别: L0\n日期: 2026-10-01\n模块: ui';
+const FM_LOW_NEW = '状态: draft\n级别: L1\n日期: 2026-10-01\n模块: ui';
 
 // --- S1：命中 + 活跃 L2 存在 → 豁免放行 ---
 {
@@ -53,7 +53,7 @@ const FM_L0_NEW = '状态: draft\n级别: L0\n日期: 2026-10-01\n模块: ui';
   const r = run(d, { staged: ['templates/_agents/scripts/x.mjs'] });
   check('S1 命中面+活跃 L2 入口 → 放行且无触达面判低输出', r.code === 0 && !r.out.includes('触达面判低'), r.out);
 }
-// --- S2：命中 + 活跃全为 L0/L1 → 阻断 ---
+// --- S2：命中 + 活跃全为 L1（低泳道）→ 阻断 ---
 {
   const d = mkfix();
   base(d);
@@ -63,12 +63,12 @@ const FM_L0_NEW = '状态: draft\n级别: L0\n日期: 2026-10-01\n模块: ui';
       && r.out.includes('workflow/intents/2026-09-28-old-l1.md') && r.out.includes('修法'),
     r.out);
 }
-// --- S2b：多个 L0/L1 活跃 → 点名最新（日期排序）---
+// --- S2b：多个低泳道（L1）活跃 → 点名最新（日期排序）---
 {
   const d = mkfix();
-  base(d, { extra: ['workflow/intents/2026-10-01-new-l0.md', FM_L0_NEW] });
+  base(d, { extra: ['workflow/intents/2026-10-01-new-low.md', FM_LOW_NEW] });
   const r = run(d, { staged: ['templates/t.md'] });
-  check('S2b 多活跃 L0/L1 → 关联入口取最新日期件', r.code === 1 && r.out.includes('2026-10-01-new-l0') && r.out.includes('共 2 件'), r.out);
+  check('S2b 多活跃 L1 → 关联入口取最新日期件', r.code === 1 && r.out.includes('2026-10-01-new-low') && r.out.includes('共 2 件'), r.out);
 }
 // --- S2c：experiment 分支 → 检查 A 降级 advisory ---
 {
@@ -200,6 +200,72 @@ const FM_L0_NEW = '状态: draft\n级别: L0\n日期: 2026-10-01\n模块: ui';
   const r = run(d, { staged: ['ok/a.ts'] });
   check('配置含非法 ERE → fail-closed 阻断并指出坏行', r.code === 1 && r.out.includes('[面清单语法错误]') && r.out.includes('[invalid('), r.out);
 }
+// --- S-hints（2026-10-13 hints-backstop）：level-hints 接入提交面判低 ---
+// 此前「就高不就低」只在 flow-kit route 输出 advisory，提交面只认 lane-surfaces → 两份清单无机器对账。
+{
+  // ① hints 命中 L3，但活跃入口只有 L2 → 判低必须拦（此前「有个 high 入口」就放行）
+  const d = mkfix();
+  base(d, { level: 'L2' });
+  w(d, '.agents/level-hints.txt', 'L3 ^src/db/\n');
+  const r = run(d, { staged: ['src/db/schema.sql'] });
+  check('S-hints hints 命中 L3 + 活跃仅 L2 → 阻断（要求入口 ≥ L3，不只「有个 high」）',
+    r.code === 1 && r.out.includes('[触达面判低]') && r.out.includes('src/db/schema.sql')
+      && r.out.includes('L3') && r.out.includes('level-hints.txt'), r.out);
+
+  // ② 升到 L3 后放行
+  const d2 = mkfix();
+  base(d2, { level: 'L3' });
+  w(d2, '.agents/level-hints.txt', 'L3 ^src/db/\n');
+  const r2 = run(d2, { staged: ['src/db/schema.sql'] });
+  check('S-hints 入口升到 L3 → 放行', r2.code === 0 && !r2.out.includes('[触达面判低]'), r2.out);
+
+  // ③ 无 hints（默认空）→ 不产生任何新阻断面（旧装户零影响）
+  const d3 = mkfix();
+  base(d3, { level: 'L1' });
+  const r3 = run(d3, { staged: ['src/db/schema.sql'] });
+  check('S-hints 未配 hints → 不触发新判定（默认空=纯语义定级）', !r3.out.includes('[触达面判低]'), r3.out);
+
+  // ④ hints 命中但无任何活跃入口 → advisory（与检查 A 同口径，豁免 docs/bootstrap 类）
+  const d4 = mkfix();
+  w(d4, '.agents/lane-surfaces.txt', '^templates/\n');
+  w(d4, '.agents/level-hints.txt', 'L2 ^src/db/\n');
+  const r4 = run(d4, { staged: ['src/db/x.sql'] });
+  check('S-hints 命中但无活跃入口 → advisory 不阻断',
+    r4.code === 0 && r4.out.includes('触达面判低') && r4.out.includes('advisory'), r4.out);
+
+  // ⑤ hints 语法错 → fail-closed（写错配置比没配置危险）
+  const d5 = mkfix();
+  base(d5, { level: 'L2' });
+  w(d5, '.agents/level-hints.txt', 'L3 [bad(\n');
+  const r5 = run(d5, { staged: ['ok/a.ts'] });
+  check('S-hints 非法 hints → fail-closed 阻断并带路径行号',
+    r5.code === 1 && r5.out.includes('[level-hints 配置错误]') && r5.out.includes('level-hints.txt'), r5.out);
+
+  // ⑥ 两份清单交叉对账：hints 登记了高风险面、lane-surfaces 为空 → advisory 点名「提交面无兜底」
+  const d6 = mkfix();
+  w(d6, '.agents/level-hints.txt', 'L2 ^src/db/\n');
+  const r6 = run(d6, { staged: ['src/db/x.sql'] });
+  check('S-hints hints 已登记但触达面清单空 → advisory 点名无兜底',
+    r6.code === 0 && r6.out.includes('level-hints 无提交面兜底'), r6.out);
+
+  // ⑦ L0 档 hints → 配置错误 fail-closed（2026-10-13 executor-review 实测 Major）
+  //   原实现接受 `L0 ^docs/`，提交面判低门当真 → 纯文档提交被硬拦，修法还让人「升级至 L0 及以上」
+  const d7 = mkfix();
+  base(d7, { level: 'L1' });
+  w(d7, '.agents/level-hints.txt', 'L0 ^docs/\n');
+  const r7 = run(d7, { staged: ['docs/readme.md'] });
+  check('S-hints L0 档 hints → fail-closed 阻断（不拿低档当门槛）',
+    r7.code === 1 && r7.out.includes('[level-hints 配置错误]') && r7.out.includes('L2 或 L3'), r7.out);
+
+  // ⑧ 路径归一化口径与判据单源一致（复用 hintLevelFor，不再各自复刻）
+  //   同一文件同时命中 hints 与触达面 → 判据里点名两处来源；Windows 反斜杠写法也要能命中
+  const d8 = mkfix();
+  base(d8, { level: 'L3' });
+  w(d8, '.agents/level-hints.txt', 'L3 ^src/db/\n');
+  const r8 = run(d8, { staged: ['src\\db\\a.sql'] });
+  check('S-hints 反斜杠路径经单源归一后仍命中（复用 hintLevelFor）',
+    r8.code === 0 && !r8.out.includes('[触达面判低]'), r8.out);
+}
 // --- git 真仓端到端：走生产发现路径（quotepath=off + diff --cached）---
 {
   const d = mkfix();