agentic-flow-kit 0.6.0 → 0.8.0

package/templates/_agents/scripts/check-loop.test.mjs

@@ -1061,7 +1061,9 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
 // ---- 场景 72-74:检查 8 生效日锚改 git 首次加入日期（2026-09-28 check8-git-anchor）----
 // 换锚前锚取**文件名前 10 字符**——项目命名规范本身即 YYYY-MM-DD-<主题>，作者日常手写该前缀，
 // 「写早」无需任何额外动作、顺手即发生 → 一条 hard 门可被平凡绕过（有未勾验项却 exit 0）。
-// 换锚后锚取 git 首次加入日期（不可手填）→ 该通道关闭。
+// 换锚后锚取 git 首次加入日期（**日常不可顺手改动**的事实）→ 关掉「改文件名」零成本通道；
+// **诚实边界（复核 P1 更正）**：该锚取 `%aI` = author date（作者自报时间戳），`git commit --date=<过去>`
+// 仍可伪造 → **不宣称「通道关闭」**，仅把伪造成本从「改文件名」抬到「主动伪造时间戳」。
 {
   {
     // 【核心回归】文件名日期写早（2026-09-01 < accCutoff 2026-09-12），但**实际是新建档**
@@ -1098,5 +1100,498 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
   }
 }
 
+// ---- 场景 75-79:检查 16 量化断言指标签名对账（2026-09-28 claim-exceeds-fix）----
+// 设计要点：本检查**只查显式签名**（`{{小写.点分}}`），不全文扫数字——理由是本仓「N 行/N 条/N 份」
+// 类表述多为历史叙述（描述某次提交当时的规模），全文扫描会产生不可消退的假阳性（P3 红线）。
+// 故本组用例的核心断言是**假阳性恒 0**：无签名时零告警；装户模板占位符（全大写）不误报。
+{
+  const MC = 'ledger.lines = ledger.lines\ndocs.count.plans = docs.count.plans\n';
+  const seedLedger = (T, lines) => w(T, '.agents/confirmations.jsonl', lines.join('\n') + '\n');
+  {
+    // 【核心回归】活跃文档留签名未回填 → warning 且提示实时值
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}', '{"doc":"b","stage":"done"}', '{"doc":"c","stage":"done"}']);
+    w(T, 'workflow/plans/p1.md', PLAN('p1', '状态: draft\n级别: L1', '\n台账共 {{ledger.lines}} 行\n'));
+    const r = run(T);
+    const o = outOf(r);
+    check('检查16:活跃文档留签名未回填 → WARN 且给出实时值 3（advisory 不阻断）',
+      r.status === 0 && o.includes('指标待回填') && o.includes('实时值 = 3'), `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【假阳性恒 0 · 核心】无签名 → 零告警（历史叙述里的裸数字不得被扫）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p2.md', PLAN('p2', '状态: draft\n级别: L1', '\n台账共 47 行，其中 13 条并录（历史叙述，非签名）\n'));
+    const r = run(T);
+    check('检查16:无签名 → 零告警（裸数字是历史叙述，不得产生假阳性）',
+      r.status === 0 && !outOf(r).includes('指标'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【假阳性恒 0 · 关键边界】装户模板占位符（全大写 SCREAMING_CASE）不误报
+    // ——不收窄形态会对本仓 plans 内 11 处合法模板占位符全部误报（实测量级）。
+    // 注：占位符**运行时拼装**而非字面写入——本仓的占位符残留门禁（doctor §5）会把字面
+    // 全大写 `{{X}}` 判为残留并改写包源副本，导致本用例在包源侧退化为测「<填写> 不误报」
+    // （仍绿但不再证明 SCREAMING_CASE 被排除）。拼装后两侧语义一致、断言强度不退。
+    const SCREAMING = (n) => '{{' + n + '}}';
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p3.md', PLAN('p3', '状态: draft\n级别: L1',
+      '\n构建 = ' + SCREAMING('BUILD_CMD') + '；端口 ' + SCREAMING('BOARD_PORT') + '；项目 ' + SCREAMING('PROJECT_NAME') + '\n'));
+    const r = run(T);
+    check('检查16:装户模板占位符（全大写 SCREAMING_CASE）→ 不误报（形态收窄）',
+      r.status === 0 && !outOf(r).includes('指标'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【fail-loud】引用未登记指标 → 明示（未登记＝无从对账，不静默放过）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p4.md', PLAN('p4', '状态: draft\n级别: L1', '\n引用 {{nope.metric}}\n'));
+    const r = run(T);
+    check('检查16:引用未登记指标 → fail-loud 出账（不静默跳过）',
+      outOf(r).includes('指标未登记'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【转义】讲语法 / 举例的行加反斜杠 → 不报（否则「文档教怎么用签名」被误判为「忘了回填」）
+    // 该需求由本检查在自己的 spec 上抓到（实现后立刻 5 处误报）。
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p8.md', PLAN('p8', '状态: draft\n级别: L1',
+      '\n写法示例如 `\\{{ledger.lines}}`（本行是讲语法，非断言）\n'));
+    const r = run(T);
+    check('检查16:转义 \\{{...}} 的行为示意 → 不报（区分「讲语法」与「真断言」）',
+      r.status === 0 && !outOf(r).includes('指标'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【守卫】check-loop 自身可加载（防语法错致整条门禁静默失效）
+    // 实证教训：本次实现期把 `continue` 误用在 forEach 回调内 → 模块 SyntaxError →
+    // check-loop 崩溃退出，而「指标告警 0 条」看起来像通过。**假绿比红更危险**，故钉死。
+    const r = run(mkfix());
+    check('检查16:check-loop 可正常加载运行（防语法错致门禁静默失效——假绿比红危险）',
+      r.status === 0 && !/SyntaxError|Illegal continue/.test(outOf(r)), `exit=${r.status}\n${outOf(r)}`);
+  }
+  {
+    // 【fail-loud】登记了指标但无取数器 → 明示「登记了却没查」（防假阴性：登记表写了却不实现）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC + 'ghost.metric = ghost.metric\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p5.md', PLAN('p5', '状态: draft\n级别: L1'));
+    const r = run(T);
+    check('检查16:登记无取数器 → fail-loud（登记了却没实现＝其实没查）',
+      outOf(r).includes('无对应取数器'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【退化语义】登记表不存在 → 静默跳过（未启用该检查的装户不应被噪声打扰）
+    const T = mkfix();
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p6.md', PLAN('p6', '状态: draft\n级别: L1', '\n台账共 {{ledger.lines}} 行\n'));
+    const r = run(T);
+    check('检查16:登记表缺失 → 静默跳过（不误报，未启用装户零噪声）',
+      r.status === 0 && !outOf(r).includes('指标'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【活跃态尺度】终态文档不扫（沿检查 4 现有尺度：历史数字是历史叙述）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p7.md', PLAN('p7', '状态: done\n级别: L1', '\n台账共 {{ledger.lines}} 行\n'));
+    const r = run(T);
+    check('检查16:终态文档不扫（历史叙述豁免，沿检查 4 尺度）',
+      r.status === 0 && !outOf(r).includes('指标待回填'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【取数正确性】docs.count.plans 应计活跃+终态全部 plans（排除 _TEMPLATE）
+    // 注：取数器与 docFiles() 同口径——须**以数字开头**（命名规范强制 `YYYY-MM-DD-` 前缀），
+    // 故 fixture 文件名必须合规（首版用 a.md/b.md 使取数为 0，暴露的是用例不合规而非判据错）。
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'docs.count.plans = docs.count.plans\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/2026-09-01-a.md', PLAN('a', '状态: draft\n级别: L1'));
+    w(T, 'workflow/plans/2026-09-02-b.md', PLAN('b', '状态: done\n级别: L1'));
+    w(T, 'workflow/plans/_TEMPLATE.md', PLAN('t', '状态: draft\n级别: L1'));
+    w(T, 'workflow/plans/2026-09-03-c.md', PLAN('c', '状态: draft\n级别: L1', '\n共 {{docs.count.plans}} 份\n'));
+    const r = run(T);
+    check('检查16:取数正确——docs.count.plans 计 3 份（排除 _TEMPLATE，含终态）',
+      outOf(r).includes('实时值 = 3'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【复核 P1 回归】转义按「逐个出现」而非整行——同一行的真签名不得被转义位藏住
+    // 复核实证：首版「行内任一 `\{{` 即整行跳过」可被这样绕过：
+    //   `… \{{a.b}} 示意… {{ledger.lines}} 未回填` → 整行静默放过（0 告警）。
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p9.md', PLAN('p9', '状态: draft\n级别: L1',
+      '\n讲语法 \\{{a.b}} 示意，但本行也有真断言 {{ledger.lines}} 未回填\n'));
+    const r = run(T);
+    check('检查16:同行「转义示意 + 真未回填」→ 真签名仍报（转义按逐个出现，不按整行）',
+      outOf(r).includes('指标待回填'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【复核 P2 回归】形态不符的签名不得静默漏过（首版只认严格小写点分 → 笔误零告警）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'workflow/plans/p10.md', PLAN('p10', '状态: draft\n级别: L1', '\n引用 {{Ledger.Lines}} 笔误\n'));
+    const r = run(T);
+    check('检查16:形态不符（大写点分笔误）→ 出账「指标形态」（不静默漏过）',
+      outOf(r).includes('指标形态'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【复核 P2 回归】形态检查不得误伤装户模板占位符（全大写 SCREAMING_CASE 仍豁免）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    const S = (n) => '{{' + n + '}}';
+    w(T, 'workflow/plans/p11.md', PLAN('p11', '状态: draft\n级别: L1',
+      '\n模板 ' + S('BUILD_CMD') + ' 与 ' + S('BOARD_PORT') + '\n'));
+    const r = run(T);
+    check('检查16:形态检查不误伤装户模板占位符（全大写仍豁免）',
+      r.status === 0 && !outOf(r).includes('指标'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+}
+
+// ---- 场景 80-90:检查 16 装户侧 derivers 动态载入（2026-09-28 adopter-derivers）----
+// 本组核心是**三条假绿防线**：装户模块坏掉时必须响亮出账，绝不静默降级成「只用内置指标」。
+// 对照：模块**缺失**是正常态（零告警）——两组行为必须可区分，否则装户无法判断自己错在哪。
+{
+  const MC2 = 'ledger.lines = ledger.lines\nmy.custom = my.custom\n';
+  const MCB = 'ledger.lines = ledger.lines\ndocs.count.plans = docs.count.plans\n'; // 仅内置指标
+  const seedLedger = (T, lines) => w(T, '.agents/confirmations.jsonl', lines.join('\n') + '\n');
+  const activePlan = (T, name, body) => {
+    // 同时写同名 intent：否则「配对断裂」hard-block 会干扰本组断言（本组只测取数器分层）
+    w(T, `workflow/intents/2026-09-01-${name}.md`, INTENT(name, '状态: draft\n级别: L1'));
+    w(T, `workflow/plans/2026-09-01-${name}.md`, PLAN(name, '状态: draft\n级别: L1', body));
+  };
+  {
+    // 【正向】装户模块存在 + 自定义指标 → 取数正确
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC2);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'my.custom': () => 7  } };\n");
+    activePlan(T, 'ok', '\n值 {{my.custom}}\n');
+    const r = run(T);
+    check('检查16装户:模块存在 + 自定义指标 → 实时值 = 7（取数正确）',
+      outOf(r).includes('my.custom') && outOf(r).includes('实时值 = 7'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【假绿防线 ①】模块语法错 → 响亮出账 + check-loop 仍正常退出（不崩）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC2);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'my.custom': () => { \n"); // 故意不闭合
+    activePlan(T, 'syn', '\n值 {{my.custom}}\n');
+    const r = run(T);
+    const o = outOf(r);
+    // 断言必须用**唯一的 warning 前缀**匹配——「装户取数器载入失败」这串字也出现在
+    // 「无对应取数器」那条的提示语里（「见上方「…载入失败」条目」），只用它匹配会**在真实条目
+    // 消失时仍然通过**（变异自验实测：静默吞掉 emit 行后该断言不翻红）。故用 `- [WARN 装户取数器载入失败]`。
+    check('检查16装户:模块语法错 → 响亮出账「装户取数器载入失败」（独立成条，明示文件）',
+      o.includes('- [WARN 装户取数器载入失败]') && o.includes('metric-derivers.cjs') && !o.includes('未登记该指标'),
+      `exit=${r.status}\n${o}`);
+    check('检查16装户:模块语法错 → 引擎自身不因装户代码崩溃（无裸 SyntaxError 崩栈）',
+      r.status === 0 && !/Illegal|at ModuleLoader|at compileSourceTextModule/.test(o),
+      `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【假绿防线 ②】取数器抛异常 → 响亮出账（明示错误）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC2);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'my.custom': () => { throw new Error('boom-xyz'); } }  };\n");
+    activePlan(T, 'thr', '\n值 {{my.custom}}\n');
+    const r = run(T);
+    check('检查16装户:取数器抛异常 → 响亮出账且明示错误',
+      outOf(r).includes('指标取数失败') && outOf(r).includes('boom-xyz'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【假绿防线 ③】返回非有限数字（字符串 / NaN / Promise）→ 拦下并明示类型
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'my.str = my.str\nmy.nan = my.nan\nmy.prom = my.prom\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', [
+      "module.exports = { derivers: {",
+      "  'my.str': () => 'not-a-number',",
+      "  'my.nan': () => NaN,",
+      "  'my.prom': () => Promise.resolve(1),",
+      "} };",
+      '',
+    ].join('\n'));
+    activePlan(T, 'types', '\n{{my.str}} {{my.nan}} {{my.prom}}\n');
+    const r = run(T);
+    const o = outOf(r);
+    check('检查16装户:返回字符串 → 取数失败（明示类型 string）',
+      o.includes('不是有限数字') && o.includes('string'), `exit=${r.status}\n${o}`);
+    check('检查16装户:返回 NaN → 取数失败', o.includes('number（NaN）'), `exit=${r.status}\n${o}`);
+    check('检查16装户:返回 Promise（误写 async）→ 取数失败并提示须同步',
+      o.includes('Promise') && o.includes('同步'), `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【区分性】模块缺失 → 零告警（与「模块坏」必须行为可区分）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MCB);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    activePlan(T, 'none', '');
+    const r = run(T);
+    check('检查16装户:模块缺失 → 零告警（正常态，与「模块坏」可区分）',
+      r.status === 0 && !outOf(r).includes('指标'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【优先级】装户定义内置同名 → 内置生效 + advisory 明示被忽略
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'ledger.lines = ledger.lines\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}', '{"doc":"b","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'ledger.lines': () => 999  } };\n");
+    activePlan(T, 'prio', '\n台账 {{ledger.lines}}\n');
+    const r = run(T);
+    const o = outOf(r);
+    check('检查16装户:内置同名 → 内置值生效（2，非装户的 999）',
+      o.includes('实时值 = 2'), `exit=${r.status}\n${o}`);
+    check('检查16装户:内置同名 → advisory 明示装户定义被忽略',
+      o.includes('被忽略'), `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【未导出】模块存在但无 derivers 导出 → fail-loud
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC2);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = {};\n");
+    activePlan(T, 'noexp', '\n{{my.custom}}\n');
+    const r = run(T);
+    check('检查16装户:模块无 derivers 导出 → 响亮出账「载入失败」（独立成条，不静默）',
+      outOf(r).includes('- [WARN 装户取数器载入失败]') && outOf(r).includes('未导出'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【旧路径迁移提示】残留首版 .mjs 文件时，须明示「已改用 .cjs」——
+    // 否则装户对着「无取数器」查不出所以然（跨版本实测：require(esm) 在 Node 18/22 不可用，
+    // 故首版 .mjs 契约在 CI 目标版本上根本不工作，必须给出可操作的迁移指引）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MC2);
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.mjs', "export const derivers = { 'my.custom': () => 7 };\n"); // 旧路径
+    activePlan(T, 'legacy', '\n{{my.custom}}\n');
+    const r = run(T);
+    const o = outOf(r);
+    check('检查16装户:残留旧 .mjs → 明示「已改用 .cjs」并给出 CJS 写法',
+      o.includes('装户取数器载入失败') && o.includes('metric-derivers.mjs') && o.includes('.cjs') && o.includes('module.exports'),
+      `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【未登记指标仍走原路】装户定义了函数但没在 registry 登记 → 报「未登记」
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'ledger.lines = ledger.lines\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'my.custom': () => 7  } };\n");
+    activePlan(T, 'unreg', '\n{{my.custom}}\n');
+    const r = run(T);
+    check('检查16装户:函数有但 registry 未登记 → 报「未登记」（两处都要）',
+      outOf(r).includes('指标未登记'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【ctx 能力】glob / read 取数正确
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'my.sql = my.sql\nmy.read = my.read\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    fs.mkdirSync(path.join(T, 'backend', 'migrations'), { recursive: true }); // w() 不建父目录
+    w(T, 'backend/migrations/001.sql', 'x');
+    w(T, 'backend/migrations/002.sql', 'x');
+    w(T, 'backend/other.txt', 'x');
+    w(T, '.agents/metric-derivers.cjs', [
+      "module.exports = { derivers: {",
+      "  'my.sql': (ctx) => ctx.glob('backend/migrations/*.sql').length,",
+      "  'my.read': (ctx) => ctx.read('backend/migrations/001.sql').length,",
+      "} };",
+      '',
+    ].join('\n'));
+    activePlan(T, 'ctx', '\n{{my.sql}} {{my.read}}\n');
+    const r = run(T);
+    const o = outOf(r);
+    check('检查16装户:ctx.glob 计数正确（2 个 sql）', o.includes('my.sql') && o.includes('实时值 = 2'), `exit=${r.status}\n${o}`);
+    check('检查16装户:ctx.read 读取正确（内容 1 字符）', o.includes('my.read') && o.includes('实时值 = 1'), `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【存量零差异】无装户模块时，内置指标行为与改前一致
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MCB);
+    seedLedger(T, ['{"doc":"a","stage":"done"}', '{"doc":"b","stage":"done"}']);
+    activePlan(T, 'base', '\n台账 {{ledger.lines}}；plans {{docs.count.plans}}\n');
+    const r = run(T);
+    check('检查16装户:无模块时内置指标照常取数（零差异）',
+      outOf(r).includes('实时值 = 2') && outOf(r).includes('实时值 = 1'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【ctx.glob 语义】自查修正回归：`**/` 须含零层、可跨段；`*` 不跨 `/`
+    // （首版实现用「先转义后 replace 星号」，实测 `src/**/*.ts` 匹配不到 `src/a/b/c.ts`）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'g.deep = g.deep\ng.flat = g.flat\ng.skip = g.skip\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    fs.mkdirSync(path.join(T, 'src', 'a', 'b'), { recursive: true });
+    fs.mkdirSync(path.join(T, 'src', 'nested'), { recursive: true });
+    w(T, 'src/a/b/c.ts', 'x');
+    w(T, 'src/top.ts', 'x');
+    w(T, 'src/nested/deep.ts', 'x');
+    fs.mkdirSync(path.join(T, 'node_modules', 'pkg'), { recursive: true });
+    w(T, 'node_modules/pkg/dep.ts', 'x');
+    w(T, '.agents/metric-derivers.cjs', [
+      "module.exports = { derivers: {",
+      "  'g.deep': (ctx) => ctx.glob('src/**/*.ts').length,",
+      "  'g.flat': (ctx) => ctx.glob('src/*.ts').length,",
+      "  'g.skip': (ctx) => ctx.glob('**/*.ts').length,",
+      "} };",
+      '',
+    ].join('\n'));
+    activePlan(T, 'glob', '\n{{g.deep}} {{g.flat}} {{g.skip}}\n');
+    const r = run(T);
+    const o = outOf(r);
+    check('检查16装户:ctx.glob 的 `**/` 含零层且跨段（src/**/*.ts 计 3）',
+      o.includes('g.deep') && o.includes('实时值 = 3'), `exit=${r.status}\n${o}`);
+    check('检查16装户:ctx.glob 的 `*` 不跨 /（src/*.ts 计 1）',
+      o.includes('g.flat') && o.includes('实时值 = 1'), `exit=${r.status}\n${o}`);
+    check('检查16装户:ctx.glob 剪枝 node_modules（**/*.ts 计 3，非 4）',
+      o.includes('g.skip') && o.includes('实时值 = 3'), `exit=${r.status}\n${o}`);
+    rmfix(T);
+  }
+  {
+    // 【ctx.glob 字面转义】点号须为字面（首版漏转义会误匹配）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'g.lit = g.lit\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, 'a.b.sql', 'x');
+    w(T, 'axb.sql', 'x');
+    w(T, '.agents/metric-derivers.cjs',
+      "module.exports = { derivers: { 'g.lit': (ctx) => ctx.glob('a.b.sql').length  } };\n");
+    activePlan(T, 'lit', '\n{{g.lit}}\n');
+    const r = run(T);
+    check('检查16装户:ctx.glob 点号按字面（a.b.sql 计 1，不含 axb.sql）',
+      outOf(r).includes('实时值 = 1'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【复核 P2 回归】模块坏但**没有任何装户指标**时，不得平白出账
+    // （首版无条件报「载入失败」——半成品模块会给清白的装户增加不可消除的噪声）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', MCB); // 只有内置指标
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'x.y': () => { \n"); // 坏模块
+    activePlan(T, 'noise', '');
+    const r = run(T);
+    check('检查16装户:坏模块 + 无装户指标 → 不出账（无判定依据不产噪声）',
+      r.status === 0 && !outOf(r).includes('装户取数器载入失败'), `exit=${r.status}\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【复核 P2 回归】内置同名 advisory 按**指标**去重（首版按 registry 行重复出账）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'ledger.lines = ledger.lines\nledger.lines = ledger.lines\nledger.lines = ledger.lines\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    w(T, '.agents/metric-derivers.cjs', "module.exports = { derivers: { 'ledger.lines': () => 999  } };\n");
+    activePlan(T, 'dedup', '\n台账 {{ledger.lines}}\n');
+    const r = run(T);
+    const n = (outOf(r).match(/被忽略/g) || []).length;
+    check('检查16装户:内置同名 advisory 按指标去重（3 行登记 → 恰 1 条）', n === 1, `实际 ${n} 条\n${outOf(r)}`);
+    rmfix(T);
+  }
+  {
+    // 【复核 P2 回归】软链接成环 → 不得无界递归（复核实测首版 depth 128、同文件重复 64 份）
+    const T = mkfix();
+    w(T, '.agents/metric-claims.txt', 'g.loop = g.loop\n');
+    seedLedger(T, ['{"doc":"a","stage":"done"}']);
+    fs.mkdirSync(path.join(T, 'loopdir', 'inner'), { recursive: true });
+    w(T, 'loopdir/inner/f.txt', 'x');
+    // 用 **dir 型 symlink**（POSIX 语义的目录软链接），而非 junction（Windows 特有、不具代表性）。
+    // 用户 2026-09-28 追问「这里用到 sh 了吗」促使追验：防环走 fs.realpathSync（Node 原生跨平台），
+    // **与 sh 无关**——故本断言在两种链接语义下都应成立。
+    let linked = false;
+    try {
+      fs.symlinkSync(path.join(T, 'loopdir'), path.join(T, 'loopdir', 'inner', 'back'), 'dir');
+      linked = true;
+    } catch { /* 无建链接权限（未开开发者模式）→ 跳过该断言 */ }
+    w(T, '.agents/metric-derivers.cjs',
+      "module.exports = { derivers: { 'g.loop': (ctx) => ctx.glob('loopdir/**/*.txt').length  } };\n");
+    activePlan(T, 'loop', '\n{{g.loop}}\n');
+    const r = run(T);
+    const o16 = outOf(r);
+    check(linked
+      // 防环生效 ⇒ 计数为 1（只有 inner/f.txt）；无防环会沿环重复到 64
+      ? '检查16装户:dir 型 symlink 成环（POSIX 语义）→ 防环生效，计数恰 1'
+      : '检查16装户:软链接成环用例跳过（本机无建链接权限）',
+      linked ? o16.includes('实时值 = 1') : true, `exit=${r.status}\n${o16}`);
+    rmfix(T);
+  }
+  {
+    // 【归属契约】装户取数模块必须归 owned——否则落回 managed，重演本单要修的缺陷本身
+    // （sync 永久报「本地已改」+ doctor WARN + check-loop 因供应链防线静默停摆）
+    //
+    // **本用例不得依赖包源 `src/`**（复核 P1 更正）：首版写 `await import('../../../src/profiles.mjs')`，
+    // 该路径在**本仓**解析到 `<repo>/src/`（存在），但在**装户安装**里 `.agents/scripts/` 只往上三层
+    // 即 `<install>/../src/`——不存在 → `ERR_MODULE_NOT_FOUND` → **整个套件崩掉**。而本测试文件是
+    // managed/shipped，故每个装户拿到的测试套件都是坏的；`npm test` 又只跑 `templates/` 副本
+    // （见 src/run-tests.mjs），所以 CI 看不见。修法：优先动态 import，失败则**降级为读源码断言**
+    // （isOwned 的判定是纯字面量列表，读源即可判，且包源/装副本都在同一路径下）。
+    let isOwned = null;
+    try {
+      ({ isOwned } = await import('../../../src/profiles.mjs'));
+    } catch { /* 装户环境无包源 src/ → 走下面的降级断言 */ }
+    if (typeof isOwned === 'function') {
+      check('检查16装户:isOwned(.agents/metric-derivers.cjs) 为真（与登记表同归 owned）',
+        isOwned('.agents/metric-derivers.cjs') === true);
+      check('检查16装户:isOwned(.agents/metric-claims.txt) 仍为真（未被本单破坏）',
+        isOwned('.agents/metric-claims.txt') === true);
+      check('检查16装户:check-loop.mjs 仍归 managed（引擎不被误划入 owned）',
+        isOwned('.agents/scripts/check-loop.mjs') === false);
+    } else {
+      // **装户环境降级断言**（复核 P1 更正）：装户没有包源 `src/profiles.mjs`，故改验**可观测事实**——
+      // 若 `metric-derivers.cjs` 已存在于盘上，它必须**不**记在 kit.json 的 managed 侧（在 managed 即为错，
+      // 那正是本单要修的缺陷形态）。未安装该模块时跳过（无判定依据的行不产出噪声）。
+      // 路径：本文件在 `<root>/.agents/scripts/`，故 kit.json 在 `../kit.json`（= `<root>/.agents/kit.json`）。
+      let verdict = null;
+      let detail = '';
+      try {
+        const kit = JSON.parse(fs.readFileSync(new URL('../kit.json', import.meta.url), 'utf8'));
+        const rel = '.agents/metric-derivers.cjs';
+        const inManaged = (kit.managed || []).some((f) => f.rel === rel);
+        const inOwned = (kit.owned || []).some((f) => f.rel === rel);
+        verdict = !inManaged;
+        detail = `managed=${inManaged} owned=${inOwned}`;
+      } catch (e) {
+        verdict = null; detail = String(e.message).slice(0, 60);
+      }
+      if (verdict === null) {
+        check('检查16装户:装户环境无法判定归属（无 kit.json）→ 跳过（不产噪声）', true);
+      } else {
+        check('检查16装户:装户环境——metric-derivers.cjs 不在 managed 侧（不在即正确）',
+          verdict === true, detail);
+      }
+    }
+  }
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/doctor.test.mjs

@@ -19,8 +19,13 @@ const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(SCRIPT_DIR, '..', '..', '..');
 const SRC = path.join(ROOT, 'src', 'doctor.mjs');
 if (!fs.existsSync(SRC)) {
-  console.error(`doctor.test.mjs：未找到 ${SRC}——仅在包源仓库（dogfooding）跑 npm test 时调用`);
-  process.exit(1);
+  // **环境不适用 ≠ 失败**（2026-09-28 修正）：本套件测的是包源 `src/doctor.mjs` 的内部函数，
+  // 装户环境没有 `src/`（那是包源）——故此处应 **SKIP 并以 0 退出**，与 check-loop.test.mjs 的
+  // 「无 sh 环境打印 SKIP 不算失败」同一口径（既有先例）。
+  // 首版 exit(1) 的代价是实测出来的：CI 新增「shipped 套件」步骤后，装户径下逐套件批量跑会把
+  // 这条 SKIP 当成真失败（doctor.test 单独 exit 1），使批量结果不可用。
+  console.error(`doctor.test.mjs：SKIP——未找到 ${SRC}（装户环境无包源 src/；本套件仅在包源仓库/dogfooding 跑 npm test 时有意义）`);
+  process.exit(0);
 }
 const { checkOwnedDrift, checkAdapterDrift, checkLedgerCoverage } = await import(pathToFileURL(SRC).href);
 
@@ -209,7 +214,7 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
       'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
     },
     adapters: {
-      '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
+      '.opencode/commands/wf-build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
       '.trae/commands/wf-build.md': `---\nname: wf-build\ndesc: trae\n---\n\n${CMD_BODY}`,
       '.zcode/agents/implementer.md': `---\nname: impl\ndesc: zcode\n---\n\n${ROLE_BODY}`,
       '.opencode/agents/implementer.md': `---\nname: impl\ndesc: oc\n---\n\n${ROLE_BODY}`,
@@ -244,7 +249,7 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
   const root = mkfixAdapter({
     pkgMarker: true,
     authority: { 'commands/build.md': `---\ndesc: x\n---\n\n${CMD_BODY}` },
-    adapters: { '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n漂移` },
+    adapters: { '.opencode/commands/wf-build.md': `---\ndesc: oc\n---\n\n漂移` },
   });
   const r = checkAdapterDrift(root);
   check('场景 11：包源环境（templates/ + modules/ 同时存在）→ skipped=true',
@@ -286,7 +291,7 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
       'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
     },
     adapters: {
-      '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
+      '.opencode/commands/wf-build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
     },
   });
   const r = checkAdapterDrift(root);

package/templates/_agents/scripts/gate-checklist.mjs

@@ -80,6 +80,7 @@ const PAIRS = [
   { doctor: '7', cl: '13', note: '经 §7 整体运行覆盖' },
   { doctor: '7', cl: '14', note: '经 §7 整体运行覆盖' },
   { doctor: '7', cl: '15', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '16', note: '经 §7 整体运行覆盖（量化断言指标签名对账，2026-09-28 claim-exceeds-fix）' },
 ];
 
 // gateChecklist：按登记表对照两侧检查项（pure function；pairs 可注入供测试）

package/templates/_agents/scripts/gen-workflow-metrics.mjs

@@ -44,8 +44,27 @@ const METRICS_P = path.join(WORKFLOW, 'metrics.md');
 const BUDGETS = path.join('.agents', 'rule-budgets.txt');
 const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
 // 活跃口径单源（board-kb-p1：枚举字面量硬编码退役——workflow-enums.txt 是唯一源）；
-// 枚举路径锚定脚本位置（fixture 测试 cwd 在临时目录，按 cwd 解析会 ENOENT）
-const ENUMS = loadEnums(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '.agents', 'workflow-enums.txt'));
+// 枚举路径锚定脚本位置（fixture 测试 cwd 在临时目录，按 cwd 解析会 ENOENT）。
+// **不能用固定上溯级数**（2026-09-28 修正）：本脚本在两处运行、深度不同——
+//   包源 `templates/_agents/scripts/` → 上溯 3 级到仓库根
+//   装户 `.agents/scripts/`          → 上溯 2 级到安装根
+// 首版硬编码 3 级，故**在每个装户安装里都解析不到枚举文件**（报错路径 `<install>/..​/.agents/…`）。
+// 实测暴露路径：CI 新增「shipped 套件」步骤后，`.agents/scripts/gen-workflow-metrics.test.mjs`
+// 场景 1 即 exit 1（workflow-enums 单源文件不可读），而包源侧同字节跑出全绿。
+// 改为**逐级上溯探测**：找到含 `.agents/workflow-enums.txt` 的那一级即用，找不到则回退标准位置让
+// loadEnums fail-loud（保持「缺失即响亮」的既有纪律，不静默兜底）。
+const resolveEnumsPath = () => {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const cand = path.join(dir, '.agents', 'workflow-enums.txt');
+    if (fs.existsSync(cand)) return cand;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // 到根
+    dir = parent;
+  }
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.agents', 'workflow-enums.txt');
+};
+const ENUMS = loadEnums(resolveEnumsPath());
 const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-metrics.mjs 整段重写，手工说明写在本行之前 -->';
 const END = '<!-- GENERATED:END -->';

package/templates/_agents/scripts/source-sync-check.mjs

@@ -18,7 +18,15 @@ function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
 const VALID_EXTS = new Set(['.md', '.mjs', '.json', '.txt']);
 // 装副本独有文件（init 渲染产物，不属双源结构）
 const RENDER_OUTPUT_FILES = new Set(['kit.json', 'settings.json', 'hooks/commit-check.config.json']);
-const TARGET_EXCLUDE = RENDER_OUTPUT_FILES;  // 向后兼容别名
+// **项目自持、按设计就该与包源骨架不同**的架子文件（2026-09-28 追加）：
+// `notes/runtime-env.md` 自述「记录本机/本项目的运行时差异……**本文件是骨架：项目按实际填写，
+// 不随 flow-kit 升级覆盖**」——即包源只发骨架、装户填实况，**两处本就应当不同**。
+// 但本工具此前按 `.md` 全量比对，导致装户一旦按文件自述填写，`--gate` 即 exit 1（CI 红）：
+// 实测（本仓自装）填写后 --gate 报 `漂移 1: notes/runtime-env.md`，回滚即恢复 0。
+// 这属「门禁范围与文件自述冲突」，非真漂移——故按渲染产物同类处理（排除）。
+// 判据：该文件是**项目内容**而非**引擎件**；引擎件（.mjs 脚本等）不在排除内，仍受双源门禁约束。
+const PROJECT_OWNED_FILES = new Set(['notes/runtime-env.md']);
+const TARGET_EXCLUDE = new Set([...RENDER_OUTPUT_FILES, ...PROJECT_OWNED_FILES]);  // 向后兼容别名（原为 RENDER_OUTPUT_FILES）
 
 function sha256(p) {
   try {
@@ -50,7 +58,10 @@ function walkMd(root) {
 export function sourceSyncCheck({ pkgRoot, target }) {
   const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
   const adapterRoot = path.join(target, '.agents');
-  const pkgFiles = walkMd(authorityRoot);
+  // **两侧都要按 TARGET_EXCLUDE 过滤**（2026-09-28 修正）：只过滤装副本一侧会把排除件
+  // 变成「包源有 / 装副本无」的**缺失**（实测：加排除后 --gate 从「漂移 1」变成「缺失 1」，
+  // 仍 exit 1）。排除的语义是「不参与双源比对」，故包源侧同样滤掉。
+  const pkgFiles = walkMd(authorityRoot).filter((f) => !TARGET_EXCLUDE.has(f));
   const tgtFiles = walkMd(adapterRoot).filter((f) => !TARGET_EXCLUDE.has(f));
   const pkgSet = new Set(pkgFiles);
   const tgtSet = new Set(tgtFiles);