agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/scripts/workflow-enums.mjs

@@ -0,0 +1,70 @@
+// workflow-enums 读取器——.agents/config/workflow-enums.txt 单源（2026-09-25 enum-single-source）
+// 消费方：check-loop.mjs / workflow-board-server.mjs / kb-search.mjs / gen-workflow-index.mjs /
+//         fill-{intent,plan,spec}.mjs（均经本读取器）。（2026-09-26 check-loop sh→node 迁移后，
+//         原先的 sh sed 消费方已退役——全部消费方统一经本读取器，无跨语言读取口径；S11 测试仍守
+//         「空格分隔 + # 注释」格式对简单工具保持可解析）
+// fail-loud 无 fallback：kit 自带该文件，缺失/坏数据属安装破损——直接抛错崩得可见，
+//   doctor §2 布局门同时把关文件存在性。禁止在任何消费方内再抄一份枚举字面量。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ENUMS_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'workflow-enums.txt');
+
+// parseEnums(text)：`key=a b` 行 → { key: ['a','b'] }；非法行/重复键/重复值抛错（单源纪律）
+export function parseEnums(text) {
+  const out = {};
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!line || line.startsWith('#')) continue;
+    const m = line.match(/^([a-z][a-z0-9.]*)=(\S.*)$/);
+    if (!m) throw new Error('workflow-enums 行格式非法（须 key=value value）: ' + line);
+    if (m[1] in out) throw new Error('workflow-enums 键重复: ' + m[1]);
+    const vals = m[2].trim().split(/\s+/);
+    if (new Set(vals).size !== vals.length) throw new Error('workflow-enums 值重复: ' + line);
+    out[m[1]] = vals;
+  }
+  return out;
+}
+
+const NEED_KEYS = [
+  'doc.status.all', 'doc.status.confirmed', 'doc.status.active', 'doc.status.terminal', 'doc.status.abandoned',
+  'incident.status.all', 'incident.status.active', 'level.all',
+];
+
+// validateEnums(enums)：跨键不变量（子集关系 + 活跃/终态互斥 + 关键态在位）——坏数据尽早抛错
+export function validateEnums(e) {
+  for (const k of NEED_KEYS) {
+    if (!Array.isArray(e[k]) || !e[k].length) throw new Error('workflow-enums 缺键或空值: ' + k);
+  }
+  const sub = (a, b) => {
+    for (const v of e[a]) if (!e[b].includes(v)) throw new Error(`workflow-enums 不变量破: ${a} 含 ${b} 外的值 ${v}`);
+  };
+  sub('doc.status.confirmed', 'doc.status.all');
+  sub('doc.status.active', 'doc.status.all');
+  sub('doc.status.terminal', 'doc.status.all');
+  sub('doc.status.abandoned', 'doc.status.all');
+  sub('doc.status.abandoned', 'doc.status.terminal');
+  sub('incident.status.active', 'incident.status.all');
+  if (e['doc.status.active'].some((v) => e['doc.status.terminal'].includes(v))) {
+    throw new Error('workflow-enums 不变量破: doc.status.active 与 doc.status.terminal 重叠');
+  }
+  if (!e['doc.status.confirmed'].includes('approved') || !e['doc.status.terminal'].includes('done')) {
+    throw new Error('workflow-enums 不变量破: approved 须在 confirmed、done 须在 terminal（确认/关单语义锚点）');
+  }
+  return e;
+}
+
+// loadEnums(file = 单源标准位置)：读文件 → parse → validate；缺文件抛错（fail-loud）
+export function loadEnums(file = ENUMS_FILE) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new Error('workflow-enums 单源文件不可读（本仓配置，见 .agents/config/ 落位）: ' + file + ' — ' + err.message);
+  }
+  return validateEnums(parseEnums(text));
+}
+
+// 模块级常量：import 即加载即校验（标准位置）
+export const ENUMS = loadEnums();
+export default ENUMS;

package/templates/engine/.agents/scripts/workflows-check.mjs

@@ -0,0 +1,260 @@
+// workflows-check：编排脚本机器 lint（2026-09-25 workflows-linter，审查改进方向 1）
+// 目的：`.agents/pipelines/_TEMPLATE.md`「解析校验先行」此前是纯 prose——role ∈ .agents/roles/、
+//       step ∈ steps/、after 引用存在且无环，全靠宿主 AI 自觉；而编排脚本的书写者与执行者是同一
+//       宿主 AI，缺外部裁决者。本工具把该纪律变成机器门：解析 .agents/pipelines/*.md 的 stages 表
+//       逐行校验，error 级 exit 1（可挂 doctor / CI），告警级 advisory 不阻断。
+//
+// 检查项（error → exit 1）:
+//   E1 缺 frontmatter（name/description/concurrency 口径见 _TEMPLATE.md）
+//   E2 concurrency 非正整数（缺省 = 2）
+//   E3 缺 stages 表（表头须含 id/after/gate 列）
+//   E4 stage 缺 id 或 id 重复
+//   E5 after 引用不存在的 stage
+//   E6 after 依赖成环
+//   E7 role 不在 .agents/roles/（词表 = 目录内 *.md 文件名）
+//   E8 step 不在 .agents/pipelines/steps/（文件名即步骤名——目录即注册表）
+//   E9 四形态（role/step/gate/human）不互斥：全空或同时 ≥2 个非空（`—`/`-`/空白 均视为空；human 列可选，缺列恒空）
+//   E10 retries 非非负整数（空 = 0，口径同 _TEMPLATE「失败且 retries > 0 → 重派」）
+// 告警（advisory，不阻断）:
+//   W1 gate 含 {a,b} 花括号展开——仅 bash 展开，PowerShell/cmd 按字面路径失败（跨宿主可移植性）
+//   W2 两个 role stage 的授权文件 token 完全相同且互相无 after 先序——并行 fan-out 同文件交叉写
+//   W3 frontmatter 缺 name（编排脚本标识）
+//   W4 human 确认门行填了 retries——用户驳回不能重派，无重试语义（视作 0）
+//
+// 排除：`_` 前缀文件（_TEMPLATE.md 是机制文档，正文含示例表——示例 step 名「部署验证」不在 steps/，
+//       机制文档不按可执行件校验）；steps/ 子目录（是扩展点注册表，非编排脚本）。
+// 表解析：取首个表头含 id+after+gate 的表格，列名归一（task / params → task、files（授权）→ files），
+//        到首个非 `|` 行截止；仅此一张表——编排脚本按机制文档只允许一张 stages 表。
+// 用法：node .agents/scripts/workflows-check.mjs [--root <目标根>] [--json]
+// 默认根 = process.cwd()（仓库根直跑即自扫）
+// 零依赖；只报告不修复（B-b 决策口径，同 check-loop 的 advisory 面）
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+import fs from 'node:fs';
+import path from 'node:path';
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+// 空值规范：em/en dash、裸连字符、空白均视为「未填」（stages 表通用约定）
+const EMPTY_CELLS = new Set(['—', '–', '-', '']);
+const normCell = (v) => { const s = String(v ?? '').trim(); return EMPTY_CELLS.has(s) ? '' : s; };
+
+function listMdNames(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)).sort();
+}
+
+function parseFm(text) {
+  const m = String(text).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^(\S+):\s*(.*)$/);
+    if (kv) fm[kv[1].trim()] = kv[2].trim();
+  }
+  return fm;
+}
+
+// splitRow：`| a | b |` → ['a','b']（去首尾竖线后按 | 切）
+function splitRow(line) {
+  return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+}
+
+// cellName：表头格 → 列名（小写取首个英文词：task / params → task、files（授权） → files）
+function cellName(c) {
+  const m = c.toLowerCase().match(/^[a-z]+/);
+  return m ? m[0] : '';
+}
+
+// parseStages：返回 stage 行数组（id/after/role/step/files/gate/human/retries + _line 行号），无表返回 null。
+// human 列可选（表头缺列 = 恒空，既有 9 列脚本零改动兼容）；导出供 wf-journal.mjs 复用同一解析口径。
+export function parseStages(text) {
+  const lines = String(text).split(/\r?\n/);
+  let headerIdx = -1;
+  let colIdx = null;
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*\|/.test(lines[i])) continue;
+    const names = splitRow(lines[i]).map(cellName);
+    if (names.includes('id') && names.includes('after') && names.includes('gate')) {
+      headerIdx = i;
+      colIdx = {};
+      names.forEach((n, k) => { if (n && !(n in colIdx)) colIdx[n] = k; });
+      break;
+    }
+  }
+  if (headerIdx === -1) return null;
+  const COLS = ['id', 'after', 'role', 'step', 'files', 'gate', 'human', 'retries'];
+  const rows = [];
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    if (!/^\s*\|/.test(lines[i])) break;
+    const cells = splitRow(lines[i]);
+    if (cells.every((c) => /^[-: ]*$/.test(c))) continue; // 分隔行 |----|
+    if (cells.every((c) => normCell(c) === '')) continue; // 全空行
+    const row = { _line: i + 1 };
+    for (const c of COLS) row[c] = colIdx[c] !== undefined ? normCell(cells[colIdx[c]] ?? '') : '';
+    rows.push(row);
+  }
+  return rows;
+}
+
+// lintWorkflowText：单文件校验（pure，词表以 Set 传入）
+export function lintWorkflowText({ file, text, roles, steps }) {
+  const errors = [];
+  const warnings = [];
+  const fm = parseFm(text);
+  if (!fm) {
+    errors.push('E1 缺 frontmatter（--- name / description / concurrency ---，口径见 _TEMPLATE.md）');
+  } else {
+    if (fm.concurrency !== undefined && fm.concurrency !== '' && !/^[1-9]\d*$/.test(fm.concurrency)) {
+      errors.push(`E2 concurrency 须为正整数（现「${fm.concurrency}」，缺省 = 2）`);
+    }
+    if (!fm.name) warnings.push('W3 frontmatter 缺 name（编排脚本标识，_TEMPLATE.md 口径）');
+  }
+
+  const rows = parseStages(text);
+  if (!rows) {
+    errors.push('E3 缺 stages 表（表头须含 id / after / gate 列——三形态各至少一行的可执行编排才有效）');
+    return { file, errors, warnings };
+  }
+
+  const byId = new Map();
+  for (const r of rows) {
+    if (!r.id) { errors.push(`E4 L${r._line} stage 缺 id`); continue; }
+    if (byId.has(r.id)) errors.push(`E4 id 重复：${r.id}（L${byId.get(r.id)._line} 与 L${r._line}）`);
+    else byId.set(r.id, r);
+    const forms = [r.role && 'role', r.step && 'step', r.gate && 'gate', r.human && 'human'].filter(Boolean);
+    if (forms.length === 0) errors.push(`E9 L${r._line} ${r.id} 四形态（role/step/gate/human）全空——须恰填一项`);
+    if (forms.length > 1) errors.push(`E9 L${r._line} ${r.id} 四形态互斥违例：同时填了 ${forms.join(' + ')}`);
+    if (r.role && !roles.has(r.role)) errors.push(`E7 L${r._line} ${r.id} role「${r.role}」不在 .agents/roles/（现有：${[...roles].join('、') || '无'}）`);
+    if (r.step && !steps.has(r.step)) errors.push(`E8 L${r._line} ${r.id} step「${r.step}」不在 steps/（现有：${[...steps].join('、') || '无'}）`);
+    if (r.retries && !/^\d+$/.test(r.retries)) errors.push(`E10 L${r._line} ${r.id} retries 须为非负整数（现「${r.retries}」，空 = 0）`);
+    if (r.gate && /\{[^}]+,[^}]+\}/.test(r.gate)) warnings.push(`W1 L${r._line} ${r.id} gate 含 {a,b} 花括号展开——仅 bash 展开，PowerShell/cmd 按字面路径失败：${r.gate}`);
+    if (r.human && r.retries) warnings.push(`W4 L${r._line} ${r.id} human 确认门行填了 retries「${r.retries}」——用户驳回不能重派，无重试语义（视作 0）`);
+  }
+
+  // after 引用存在性 + 成环（DFS 三色）
+  const ids = new Set(byId.keys());
+  const deps = new Map();
+  for (const [id, r] of byId) {
+    deps.set(id, r.after ? r.after.split(/[,，、\s]+/).filter(Boolean) : []);
+  }
+  for (const [id, ds] of deps) {
+    for (const d of ds) if (!ids.has(d)) errors.push(`E5 ${id} after 引用不存在的 stage：${d}`);
+  }
+  const color = new Map();
+  let cycle = '';
+  const dfs = (id) => {
+    color.set(id, 1);
+    for (const d of deps.get(id) || []) {
+      if (!ids.has(d)) continue;
+      const c = color.get(d) || 0;
+      if (c === 1) { cycle = `${d} → ${id}`; return true; }
+      if (c === 0 && dfs(d)) return true;
+    }
+    color.set(id, 2);
+    return false;
+  };
+  for (const id of ids) {
+    if (!color.get(id) && dfs(id)) { errors.push(`E6 after 依赖成环：${cycle}（闭环上一对）`); break; }
+  }
+
+  // W2 授权文件交叉：role stage 间完全相同 token 且互相无 after 先序（有先序 = 串行接力，不算交叉）
+  if (!errors.some((e) => e.startsWith('E5') || e.startsWith('E6'))) {
+    const depAll = new Map();
+    const depClosure = (id) => {
+      if (depAll.has(id)) return depAll.get(id);
+      const s = new Set();
+      depAll.set(id, s); // 先占位防递归环（E6 已排除，稳妥起见）
+      for (const d of deps.get(id) || []) {
+        if (!ids.has(d)) continue;
+        s.add(d);
+        for (const x of depClosure(d)) s.add(x);
+      }
+      return s;
+    };
+    const tokensOf = (r) => new Set((r.files || '').split(/[,，、\s]+/).map((t) => t.trim()).filter(Boolean));
+    const roleRows = [...byId.values()].filter((r) => r.role && r.files);
+    for (let i = 0; i < roleRows.length; i++) {
+      for (let j = i + 1; j < roleRows.length; j++) {
+        const a = roleRows[i];
+        const b = roleRows[j];
+        const shared = [...tokensOf(a)].filter((t) => tokensOf(b).has(t));
+        if (!shared.length) continue;
+        if (depClosure(a.id).has(b.id) || depClosure(b.id).has(a.id)) continue;
+        warnings.push(`W2 role stage ${a.id} 与 ${b.id} 授权文件交叉且无 after 先序（并行 fan-out 同文件交叉写）：${shared.join('、')}`);
+      }
+    }
+  }
+
+  return { file, errors, warnings };
+}
+
+// lintWorkflows：扫 <root>/.agents/pipelines/（pure function，测试/doctor 共用）
+// 返回 { root, roles, steps, files: [{file, errors, warnings}], errorCount, warningCount }
+export function lintWorkflows({ root }) {
+  const wfRoot = path.join(root, '.agents', 'pipelines');
+  const roles = new Set(listMdNames(path.join(root, '.agents', 'roles')));
+  const steps = new Set(listMdNames(path.join(wfRoot, 'steps')));
+  const files = (fs.existsSync(wfRoot) && fs.statSync(wfRoot).isDirectory())
+    ? fs.readdirSync(wfRoot, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.md') && !e.name.startsWith('_'))
+        .map((e) => e.name)
+        .sort()
+    : [];
+  const results = files.map((f) => lintWorkflowText({
+    file: f,
+    text: fs.readFileSync(path.join(wfRoot, f), 'utf8'),
+    roles,
+    steps,
+  }));
+  return {
+    root,
+    roles: [...roles],
+    steps: [...steps],
+    files: results,
+    errorCount: results.reduce((n, r) => n + r.errors.length, 0),
+    warningCount: results.reduce((n, r) => n + r.warnings.length, 0),
+  };
+}
+
+function printResult(result) {
+  console.log('▶ workflows-check（.agents/pipelines/ 编排脚本 lint）');
+  console.log(`  编排脚本 ${result.files.length} 份 ｜ roles 词表 ${result.roles.length} ｜ steps 词表 ${result.steps.length}`);
+  for (const f of result.files) {
+    if (!f.errors.length && !f.warnings.length) {
+      console.log(`  ✅ ${f.file}`);
+    } else {
+      console.log(`  ${f.errors.length ? '❌' : '⚠️ '} ${f.file}（${f.errors.length} error / ${f.warnings.length} warning）`);
+      for (const e of f.errors) console.log(`    - ${e}`);
+      for (const w of f.warnings) console.log(`    - ⚠️ ${w}`);
+    }
+  }
+  const tail = result.errorCount
+    ? `❌ ${result.errorCount} error / ${result.warningCount} warning——error 须修复后才可执行编排（解析校验先行）`
+    : `${result.warningCount ? `⚠️  0 error / ${result.warningCount} warning（advisory 不阻断）` : '✅ 0 error / 0 warning'}`;
+  console.log(`  ${tail}`);
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('workflows-check.mjs');
+if (isMain) {
+  let root = process.cwd();
+  let json = false;
+  for (let i = 2; i < process.argv.length; i++) {
+    const a = process.argv[i];
+    if (a === '--root') root = path.resolve(process.argv[++i] ?? fail('--root 缺少值'));
+    else if (a === '--json') json = true;
+    else fail(`未知选项：${a}（workflows-check --root <dir> / --json）`);
+  }
+  const result = lintWorkflows({ root });
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      root: result.root,
+      files: result.files,
+      errorCount: result.errorCount,
+      warningCount: result.warningCount,
+    }, null, 2) + '\n');
+  } else {
+    printResult(result);
+  }
+  process.exit(result.errorCount ? 1 : 0);
+}
+export default lintWorkflows;

package/templates/engine/.agents/settings.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "dotnet build",
+      "dotnet run",
+      "npm run",
+      "npm install",
+      "npm ci",
+      "node",
+      "git status",
+      "git diff",
+      "git add",
+      "git commit",
+      "git log",
+      "git push",
+      "chrome"
+    ],
+    "deny": [
+      "dotnet ef",
+      "git reset --hard",
+      "git push --force",
+      "git push -f",
+      "drop database",
+      "--no-verify"
+    ],
+    "ask": [
+      "git checkout",
+      "git clean",
+      "git branch -D",
+      "rm -rf"
+    ]
+  }
+}

package/templates/engine/.agents/skills/arena/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: arena
+description: 设计选型 bakeoff——同一 brief 给 N 个独立臂（不同模型/架构/数据形状），按验收判据选底座并嫁接最佳部分；供「两个方案争不出高下 / 没有先例的设计」时使用。
+---
+
+# arena — 并行对比选型
+
+## 触发
+
+- 设计分叉没有先例，两个以上方案都说得通。
+- 用户说「对比一下 / 各做一个看看 / 选型」。
+- 方案会锁定后续实现形状，选错返工成本高。
+
+## 核心
+
+**同一 brief，独立臂，裁判选底座 + 嫁接。** 不是并行实现同一个文件；是并行**提案**，再选一个底座。臂之间不共享上下文（防锚定）。
+
+## 步骤
+
+1. **固定 brief**：目标、约束、验收判据、非目标、证据要求。每个臂拿到**逐字相同**的 brief。
+2. **选臂**：2–3 个，差异轴要真实——不同模型 / 不同架构 / 不同数据形状。不要跑 N 个同构臂。
+3. **并行派发**：一个 `task` 批次；每个臂返回：方案、取舍、风险、最小证明（能跑的原型/测试/伪代码）。
+4. **裁判**：按验收判据逐项打分；选**一个底座**；列出从其他臂**嫁接**的具体部分；被拒方案写一句为什么。
+5. **落地**：实现底座 + 嫁接；对选定设计跑 `.agents/skills/blast-radius/SKILL.md`；再 `verify --scope`。
+6. **落账**：`workflow/delegations.md` 每个臂一行 + 裁判结论；长跑加 `decisions.tsv` 一行。
+
+## 输出
+
+| 臂 | 方案 | 强项 | 风险 | 最小证明 | 结论 |
+|---|---|---|---|---|---|
+| A | … | … | … | … | 底座 / 嫁接 X / 拒 |
+| B | … | … | … | … | … |
+
+- **底座**：选谁、为什么。
+- **嫁接**：从其他臂拿哪几块、怎么合。
+- **拒绝**：每个被拒方案一句理由。
+- **未决**：需要 owner 拍板的产品/偏好判断。
+
+## 本仓落点
+
+- 派发：`task` 的 `tasks[]` 批次；`model-roles.json` 的 `judgment` 角色。
+- 复核：选定设计后按 `.agents/skills/interrogate/SKILL.md` 多镜拆。
+- 证明：`.agents/skills/blast-radius/SKILL.md`（安全因为 X 要跑代码）。
+- 落账：`workflow/delegations.md`；聚合 `node .agents/scripts/agg-delegations.mjs`。
+
+## 边界
+
+- 臂之间不共享结论；共享 brief 即可。
+- 不把 N 个方案全合进去——选一个底座，嫁接要具体到文件/函数。
+- 耦合实现（同一文件/同一契约）不用 arena，用串行。

package/templates/engine/.agents/skills/autonomous-run/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: autonomous-run
+description: 无人值守长跑合同——长任务/过夜时逐单元签收、自底向上落地、何时停机；供主智能体在用户离开前立约使用（可挂 pipeline-run 驱动）。
+---
+
+# autonomous-run — 无人值守合同
+
+用于长跑（过夜 / 用户离开）。**推进方式**：按本合同的逐单元签收；编排可挂 `pipeline-run` 驱动，或走 `.agents/pipelines/` / 手动阶段。**不放宽任何门禁与确认门**，只约定推进节奏与停机条件。
+
+## 立约（开工前一次）
+
+1. **授权面**：写明允许改的目录/分支、本次 run 的目标文档。
+2. **禁做清单**：远程 push、部署、删数据、直改 workflow 状态、`--no-verify`——仍需用户明确指令。
+3. **预算**：修复环沿用 3 次上限（pipeline-run 同一口径）；不新增预算。
+4. **停机联系人**：用户回来即停，汇报现状。
+5. **决策留痕**：长跑/过夜按 `.agents/skills/show-me-your-work/SKILL.md` 记 `decisions.tsv`（append-only，证据是指针）；提交与否按 stakes 定。
+
+## 逐单元签收（每个 implement / fix 工单）
+
+1. 按授权文件实现，偏离即停（计划外文件 / 公共接口 / 新依赖）。
+2. 跑 `node .agents/scripts/verify.mjs --scope`，必须退出码 0。
+3. 记录绿凭证的 `headShort`（s15 指纹）；**HEAD 变了或凭证超 24h 窗 → 重跑**，不沿用旧绿。
+4. 签收后才 `next`；不绿不推进，不攒批。
+
+## 落地顺序
+
+- 按依赖自底向上，一个单元一笔提交，Conventional Commits 中文。
+- 跨单元不合并提交；后一单元基于前一单元的已签收 HEAD。
+- 同一单元返工后，旧凭证作废，重新签收。
+
+## 停机条件（任一触发即停并汇报）
+
+- 修复环达 3 次仍红。
+- 指纹不匹配 / 绿凭证过期且重跑仍红。
+- 需要越界文件、公共接口变更或新依赖。
+- 同一根因的两次假设都被证伪。
+- 用户回来或发出任何新指令。
+
+## 恢复
+
+中断后先按 `.agents/skills/session-resume/SKILL.md` 重建；pipeline-run 运行对账可跑 `status --run <id>`；已签收单元不重做。
+
+## 汇报
+
+阶段条 / 各门结果 / 提交链（sha + 标题）/ 未决项与需要用户决定的事项。

package/templates/engine/.agents/skills/blast-radius/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: blast-radius
+description: 小改动的影响面证明——找出「安全因为 X」的那一个事实，并用跑代码证明，而不是写一篇听起来对的说明；供「这改动还会碰坏什么 / 小 diff 不放心」类复核使用。
+---
+
+# blast-radius — 影响面证明
+
+## 触发
+
+- 用户问「这改动还会碰坏什么 / blast radius / 有没有漏」。
+- diff 很小但跨了函数边界、共享状态、序列化格式、DB 列、feature flag。
+- 复核时对「应该没事」不放心，需要可复核的证据。
+
+## 核心
+
+**不要相信自己的书面分析。** 影响面说明读起来总是像对的，无论真假。找出整个判断依赖的**一个或两个事实**，用跑代码证明它们；证明不了就写 `unproven`。
+
+列调用者不是本事——grep 一秒就能列。本事在 grep 停下来的地方：库源码、固定版本、运行时顺序、wire format、DB 列、另一门语言读同一份字节、三跳之后的下游。
+
+## 确定性阶梯（每个事实标停在哪一级）
+
+1. **我说是**——单独不算证据。
+2. **指到行**——真实 `file:line`，或库自己的源码。
+3. **反例走不通**——把失败路径一步步走完，确认到不了。
+4. **跑过**——一个小脚本/测试调用真实代码，错了就大声失败。
+5. **在运行的应用里复现**——端到端证据。
+
+第 4 级通常就是一个小脚本：import 应用同一份库，调用你担心的那个函数，断言结果。
+
+## 步骤
+
+1. **读改动**：diff、新增/修改/删除的符号、行为差异（包括 diff 没写出来的部分）。用 `git log -S`、`xd://lsp` references、`kb-search` 补上下文。
+2. **找那一个安全事实**：多数看起来危险的改动，安全只因为一个事实（例：「这个调用只丢已死的缓存项，别的什么都不做」）。把时间花在这里，不要列一长串 maybe。
+3. **看 grep 停下的地方**：库源码与固定版本、本地 patch、微任务/卸载/teardown 顺序、API 返回的 JSON、DB 列、wire format、另一门语言、feature flag、三跳下游。
+4. **诚实列风险**：每条给发生概率与代价、`file:line`、怎么查；确认的清单独列。搜不到也是答案，不要编调用者或 API。
+5. **证明那一个事实**：写脚本/测试跑真实代码，贴输出。证明不了 → `unproven`。
+6. **大/宽改动**：让多个模型独立回答同一问题，再合并——不同模型抓不同的真 bug。
+
+## 输出格式
+
+- **改了什么**：包括不明显的部分。
+- **安全因为**：那一个事实 + 停在第几级 + 证明输出；证明不了写 `unproven`。
+- **风险**：每条 = 怎么坏 + `file:line` + 概率/代价 + 怎么查；重要的贴证明。
+- **已排除**：查过且为什么没事。
+- **合入前**：最便宜的、能抓住真 bug 的测试/复现（含你写的脚本）。
+
+## 本仓落点
+
+- 复核：`.agents/commands/review.md` P1「影响面证明」。
+- 设计：`.agents/commands/stages.md` Design 章契约面变更。
+- 机器面：`verify-scope.mjs` 只算 diff 面；本技能补「为什么安全」。
+- 证据：证明脚本放 `tmp/` 或随 PR 提交；不要只写结论。
+- 边界：本技能不替代 `verify` 门禁；它证明的是「没碰坏别处」，不是「本次改动正确」。

package/templates/engine/.agents/skills/csharp-quality-gates/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: csharp-quality-gates
+description: C# 后端质量门——CRAP（复杂度×覆盖）、变异测试、重复代码三道确定性门的手动触发入口；内置本机 coverlet 采集失效的 TEMP 改道与「0 覆盖是采集故障还是真没测」的判别、报告解读判据、补测优先级排序；供「这改动有没有测试兜住 / 哪些方法该先补测试 / 复杂度或重复有没有超标 / 后端质量现状盘点」类问题使用。命令入口 .agents/skills/csharp-quality-gates/scripts/quality-gates.mjs。
+---
+
+# csharp-quality-gates — C# 后端质量门（手动触发）
+
+后端代码与 ub-mode 的三阶段纪律对位（Uncle Bob 的 crapper/dryer/mutator 不支持 C#，本仓用等价物替代）：
+
+| ub-mode 门 | Uncle Bob 原工具 | 本仓等价物 | 判据 |
+|---|---|---|---|
+| Crapper（Then Make it Right） | crapper | **dotnet-crap**（Crap4DotNet） | `CRAP = CC²×(1-cov)³+CC`，阈值默认 30 |
+| Mutator（Then Make it Right） | mutator | **dotnet stryker**（Stryker.NET） | 变异得分（killed/total） |
+| Dryer（Then Make it Right） | dryer | **PMD CPD**（`--language cs`） | 结构重复，token 数 |
+
+下文 `qg` 代指 `node .agents/skills/csharp-quality-gates/scripts/quality-gates.mjs`。
+
+## 触发 / 不触发
+
+- **触发**：「后端质量现状 / 这改动有没有测试兜住 / 哪些方法该先补测试 / 复杂度有没有超标 / 有没有重复代码 / 变异测试怎么跑」；改动落在 `backend/` 且涉及业务逻辑；补完一批测试想验证"测试是不是真的在测"。
+- **不触发**：纯前端改动（本仓 C# 门不覆盖 `frontend/`）；只想知道"能不能编译"（用 `commit-check.config.json` 的 build 段）；只想知道"跑不跑得过测试"（直接 `dotnet test`）。
+- **不替代** `verify` 门禁：本技能是**手动触发**的诊断与盘点工具，不进提交门禁，不改任何门禁配置。
+
+## 0. 前置探测
+
+```bash
+qg doctor
+```
+
+逐项打印工具是否就位：`dotnet` / `dotnet-crap` / `dotnet-stryker` / `pmd` / `java` / 单测工程 / 解决方案。缺装时脚本会打印安装命令：
+
+```bash
+dotnet tool install -g Crap4DotNet
+dotnet tool install -g dotnet-stryker
+# PMD：下载 pmd-dist-<ver>-bin.zip 解压到 ~/.agents/tools/pmd/（含 lib/ 与 conf/ 的那层）
+```
+
+机器上的实际路径登记在 `.agents/notes/runtime-env.local.md`（git-ignore，单源纪律）；脚本按 `环境变量 → 已知安装位 → PATH` 解析，不硬编码绝对路径。
+
+## 1. 三道门
+
+```bash
+qg coverage                 # 跑单测收覆盖率（TEMP 改道内置）
+qg crap [--threshold 30] [--top 15] [--min-crap N] [--coverage <绝对路径>]
+qg dup [--minimum-tokens 100] [--top 10]
+qg mutate "<glob>"          # 变异测试，必须定点
+qg all                      # coverage → crap → dup（不含 mutate，太慢）
+```
+
+退出码：`0` 通过 / `1` 门未达标（有方法超阈值、有重复块、变异得分未达标）/ `2` 用法·配置·采集失败。**退出码 2 一律不是「通过」**，是"没跑起来"。
+
+产物落在 `.agents/tmp/quality-gates/`（git-ignore）：覆盖率 XML、`crap-report.json`、Stryker 报告。
+
+## 2. 采集失效陷阱（本机已知，必读）
+
+**coverlet 在本机默认 TEMP 下会静默产出 0% 覆盖率。**
+
+- 现象：测试全绿、代码确实调了生产服务，但 cobertura 里 `lines-covered=0`——每个类每行 hits 都是 0。
+- 根因：coverlet 把插桩后的模块写到 `%TEMP%\<模块名>_<guid>` 再加载；该文件在默认 TEMP 下丢失，testhost 退出时抛**未处理** `FileNotFoundException`（进程 -532462766），命中数据没落进报告。
+- 判据：测试明明 `new XxxService(...)` 调了生产代码，cobertura 却全 0。
+- 修法：`qg coverage` 已把 `TEMP`/`TMP` 改道到 `.agents/tmp/quality-gates/tmp`；实测改道后 `lines-covered=23701/37805`（line-rate 0.6269）。
+- **脚本守卫**：`coverage` 在 `lines-valid>0 && lines-covered==0` 时**报错退出 2**，不产出"零覆盖"结论；`crap` 拿到这种文件也会拒跑。
+
+> 同机另两条死路：`--collect:"Code Coverage"`（Microsoft.CodeCoverage）只产出 0KB 空文件；`/p:CollectCoverage=true` 需要 `coverlet.msbuild` 包（本仓只有 `coverlet.collector`）。**别再在这两条上耗时间。**
+
+## 3. 报告解读：先分清「采集坏了」vs「代码没被测到」
+
+顺序不能颠倒——先确认采集是好的，再谈覆盖率。
+
+1. **采集是否可信**：看 `qg coverage` 输出的 `lines-covered`。0 → 采集故障（§2），先修采集，**禁把 0% 当结论**。
+2. **CRAP 表读法**：按 CRAP 从差到好排，最上面那些"又复杂又没覆盖"才是优先级；**别只看 CRAP 绝对值**——一个 CC=2 但覆盖 100% 的方法 CRAP=2，不是问题。
+3. **变异得分读法**：得分低有两种成因，处置完全不同——
+   - (a) **测试无效**：NoCoverage 少、被杀比例低 → 断言太松，测试通过但没验证逻辑；
+   - **本仓实测是 (b)**：NoCoverage 多（607/23274 变异点落在没人测到的代码路径上）→ **该路径缺测试**，不是断言不够严。先分清再动手。
+4. **重复检测读法**：PMD 的 `--minimum-tokens` 是相似度旋钮（默认 100 ≈ dryer 的 0.8 相似度档）；同一文件内多行命中优先看"三处共用同一 helper"这类结构性重复（`PurchaseOrderService.cs` 2026-10-31 基线快照 451/775 行、62 行/397 token；行号为基线值，非当前）。
+
+## 4. 补测优先级
+
+**判据 = 零覆盖 ∧ 高 CRAP**，不是 CRAP 绝对值。脚本已按此排好序（`qg crap` 输出的"零覆盖且超阈值"清单）。
+
+本仓 2026-10-31 基线：方法总数 1622，**零覆盖 1264（78%）**，超阈值 323，其中 319 个同时零覆盖。Top：
+
+| 方法 | CC | CRAP |
+|---|---|---|
+| `PMLService.FinishMatchAsync` | 74 | 5550 |
+| `MaterialCodeImportService.PreviewAsync` | 58 | 3422 |
+| `OutboundOrderService.MatchAndLockCoreAsync` | 53 | 2862 |
+| `MaterialCodeService.CreateAsync` | 51 | 2652 |
+| `MaterialCodeImportService.ValidateImportRowsAsync` | 49 | 2450 |
+
+**为什么 78% 零覆盖**：只有集成测试覆盖的服务在常规档位是盲区——`tests/Shipyard.Material.IntegrationTests/` 需要 DB，CI mid 档 `backend-test` 带 `--unit-only`（不连测试库），full 档因 CI 未定义 `TEST_DB_CONN` 走共享 dev 库逃生。`ExchangeRateImportService` 就是典型：唯一测试在集成测试工程里，变异测试里把 Excel 表头字符串全换成 `""` 依然全绿。
+
+补测方向因此是两条：**把不碰 DB 的纯逻辑下沉到单测**（Excel 表头/模板生成、校验口径这类），或**给 CI 配 `TEST_DB_CONN`** 走真实集成档。
+
+## 5. 输出格式
+
+做完盘点后按这四节给结论：
+
+- **现状**：三道门各自的数字（覆盖率 line-rate / CRAP 超阈值数与占比 / 重复块数 / 变异得分），标注采集是否可信。
+- **风险**：按"零覆盖 ∧ 高 CRAP"排序的前 N 个方法，含 `file` 定位。
+- **原因**：区分"测试无效"与"代码没被测到"；若属后者，指出盲区来源（集成测试档位 / DB 依赖 / 纯逻辑未下沉）。
+- **下一步**：具体到"给哪个方法补哪种测试"；不要停在"建议提高覆盖率"。
+
+## 6. 本仓落点与边界
+
+- 门禁单源：`.agents/hooks/commit-check.config.json`（build 段 = `dotnet build Shipyard.Material.sln`；**checks 段当前为空**，本地提交门不跑测试）。本技能**不改**该文件。
+- 与 ub-mode 的接口：First Make it Work → 补测试（让 TDD 有落点）；Then Make it Right → 三道门；Practice → Keep a Log（本技能的结论就是决策日志的素材）。
+- 与 `review-method` 的接口：复核 diff 时，"影响面证明"可用本技能的 dup/crap 补机器证据。
+- 边界：只跑**单测工程**（集成测试要 DB，本机无 DB 会挂）；Stryker **必须定点**（全量 2 万+ 变异点不可接受）；不写任何仓库文件（除本技能自身目录）；不提交代码。