agentic-flow-kit 0.3.1 → 0.5.0

package/templates/_agents/scripts/fill-plan.test.mjs

@@ -0,0 +1,67 @@
+// fill-plan.test.mjs — fill-plan 工具测试（2026-09-25 doc-fill-tools）
+import { renderPlan } from './fill-plan.mjs';
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log('PASS ' + name); }
+  else { failCount++; console.log('FAIL ' + name + (detail ? '——' + detail : '')); }
+}
+
+// ---- 场景 1：L1 极简 2 节 ----
+{
+  const { body } = renderPlan({ topic: 't', level: 'L1' });
+  const sections = body.match(/^##\s.+$/gm) || [];
+  check('S1 L1 含节 ## 改动面', body.includes('## 改动面'));
+  check('S1 L1 含节 ## 验证方式', body.includes('## 验证方式'));
+  check('S1 L1 共 3 节（改动面 + 验证方式 + 确认与复核）', sections.length === 3, '实际 ' + sections.length + ' 节');
+}
+
+// ---- 场景 2：L2 完整 4 节 ----
+{
+  const { body } = renderPlan({ topic: 't', level: 'L2' });
+  const sections = body.match(/^##\s.+$/gm) || [];
+  check('S2 L2 含节 ## 改动面', body.includes('## 改动面'));
+  check('S2 L2 含节 ## 任务拆解', body.includes('## 任务拆解'));
+  check('S2 L2 含节 ## 执行顺序', body.includes('## 执行顺序'));
+  check('S2 L2 含节 ## 验证方式', body.includes('## 验证方式'));
+  check('S2 L2 共 5 节（4 节 + 确认与复核）', sections.length === 5, '实际 ' + sections.length + ' 节');
+}
+
+// ---- 场景 3：L3 与 L2 同结构 ----
+{
+  const { body } = renderPlan({ topic: 't', level: 'L3' });
+  check('S3 L3 含节 ## 改动面', body.includes('## 改动面'));
+  check('S3 L3 含节 ## 任务拆解', body.includes('## 任务拆解'));
+}
+
+// ---- 场景 4：非法 level 抛错 ----
+{
+  let threw = false;
+  try { renderPlan({ topic: 't', level: 'X' }); } catch { threw = true; }
+  check('S4 非法 level 抛错', threw);
+}
+
+// ---- 场景 5：默认 L1 ----
+{
+  const { body } = renderPlan({ topic: 't' });
+  check('S5 默认级别 L1', /级别:\s*L1/.test(body.match(/^---([\s\S]*?)---/)[1]));
+}
+
+// ---- 场景 6：frontmatter 含 3 字段（与 _TEMPLATE 对齐——L1 plan 无日期字段）----
+{
+  const { body } = renderPlan({ topic: 't', level: 'L1' });
+  const fm = body.match(/^---([\s\S]*?)---/)[1];
+  check('S6 frontmatter 含状态', /状态:/.test(fm));
+  check('S6 frontmatter 含级别', /级别:/.test(fm));
+  check('S6 frontmatter 含模块', /模块:/.test(fm));
+}
+
+// ---- 场景 7：与入口配对提示 ----
+{
+  const { body } = renderPlan({ topic: 't', level: 'L1' });
+  check('S7 含「对应入口」段', body.includes('对应入口：'));
+  check('S7 含「对应 spec」段（L1 可省略）', body.includes('对应 spec：'));
+}
+
+console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
+process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/fill-spec.mjs

@@ -0,0 +1,52 @@
+// flow-kit fill-spec：起草 spec 草稿（功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估 共 5 节）
+// 用法：node .agents/scripts/fill-spec.mjs --topic "test" --output /tmp/x.md
+import fs from 'node:fs';
+import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
+
+const TODAY = new Date().toISOString().slice(0, 10);
+const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
+
+function parseArgs(argv) {
+  const out = { topic: null, level: 'L2', output: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
+    if (a === '--topic') out.topic = next();
+    else if (a === '--level') out.level = next();
+    else if (a === '--output') out.output = next();
+  }
+  return out;
+}
+
+function fail(msg) { console.error(`❌ ${msg}`); process.exit(1); }
+
+const SECTIONS = [
+  { title: '功能行为', hint: '<完整描述本 spec 涉及的功能 / 行为变化；分用户场景列；含边界与异常>' },
+  { title: '数据流', hint: '<请求→处理→持久化→回应的端到端路径；标出各环节涉及的服务 / 表 / 缓存 / 第三方调用>' },
+  { title: '系统改动', hint: '<分模块列出本 spec 引入的所有改动；含新增 / 修改 / 删除；与 plan §改动面 一一对应>' },
+  { title: '约束遵守映射', hint: '<逐条对照根 AGENTS.md 与目录级 AGENTS.md（如有）的红线 / 约束，说明本 spec 如何满足；逐条回应而非简单列举>' },
+  { title: '风险评估', hint: '<列出本 spec 引入的风险点：数据 / 接口 / 性能 / 安全 / 回滚难度 / 用户影响；评估每个的等级与缓解措施>' },
+];
+
+export function renderSpec({ topic, level = 'L2', date = TODAY }) {
+  if (!LEVELS.includes(level)) throw new Error(`level 不在枚举 ${LEVELS.join('|')}：${level}`);
+  const fm = `---\n状态: draft\n级别: ${level}\n日期: ${date}\n模块: pipeline\n备注: <spec 关联 intent / plan 的同名主题>\n---\n`;
+  let body = `# SPEC — ${topic}\n\n<!-- 与 intents/ 下同名入口文档配对；L2/L3 必须先有 ../intents/YYYY-MM-DD-<主题>.md approved -->\n<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled；级别∈L0/L1/L2/L3；正文不再写状态/级别行 -->\n\n`;
+  for (const { title, hint } of SECTIONS) {
+    body += `## ${title}\n\n${hint}\n\n`;
+  }
+  body += `## 确认与复核\n\n- 确认日期：\n- 复核：L3 必须独立复核（independent-reviewer，新会话）；L2 推荐独立复核；L1 可省\n`;
+  return { frontmatter: fm, body: fm + body, sections: SECTIONS.map((s) => s.title) };
+}
+
+const isMain = import.meta.url === `file:///${process.argv[1]}` || process.argv[1]?.endsWith('fill-spec.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  if (!a.topic || !a.output) fail('必填：--topic / --output；选填：--level（默认 L2）');
+  if (!LEVELS.includes(a.level)) fail(`level 必须在 ${LEVELS.join('|')}：${a.level}`);
+  const { body } = renderSpec(a);
+  fs.mkdirSync(path.dirname(a.output), { recursive: true });
+  fs.writeFileSync(a.output, body);
+  console.log(`✅ 已生成 spec 草稿：${a.output}（状态 draft / 级别 ${a.level}）`);
+}

package/templates/_agents/scripts/fill-spec.test.mjs

@@ -0,0 +1,61 @@
+// fill-spec.test.mjs — fill-spec 工具测试（2026-09-25 doc-fill-tools）
+import { renderSpec } from './fill-spec.mjs';
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log('PASS ' + name); }
+  else { failCount++; console.log('FAIL ' + name + (detail ? '——' + detail : '')); }
+}
+
+// ---- 场景 1：5 节正文齐 ----
+{
+  const { body } = renderSpec({ topic: 'test', level: 'L2' });
+  const expectedSections = ['功能行为', '数据流', '系统改动', '约束遵守映射', '风险评估', '确认与复核'];
+  for (const s of expectedSections) check('S1 含节 ## ' + s, body.includes('## ' + s));
+  check('S1 共 6 节标题', (body.match(/^##\s/gm) || []).length === 6);
+}
+
+// ---- 场景 2：frontmatter 含 5 字段 ----
+{
+  const { body } = renderSpec({ topic: 't', level: 'L2' });
+  const fm = body.match(/^---([\s\S]*?)---/);
+  check('S2 frontmatter 含状态 draft', /状态:\s*draft/.test(fm[1]));
+  check('S2 frontmatter 含级别 L2', /级别:\s*L2/.test(fm[1]));
+  check('S2 frontmatter 含日期', /日期:\s*\d{4}-\d{2}-\d{2}/.test(fm[1]));
+  check('S2 frontmatter 含模块', /模块:/.test(fm[1]));
+  check('S2 frontmatter 含备注', /备注:/.test(fm[1]));
+}
+
+// ---- 场景 3：L3 也合法（默认 L2，但显式 L3 也接受）----
+{
+  const { body } = renderSpec({ topic: 't', level: 'L3' });
+  check('S3 L3 合法', /级别:\s*L3/.test(body.match(/^---([\s\S]*?)---/)[1]));
+}
+
+// ---- 场景 4：非法 level 抛错 ----
+{
+  let threw = false;
+  try { renderSpec({ topic: 't', level: 'XX' }); } catch { threw = true; }
+  check('S4 非法 level 抛错', threw);
+}
+
+// ---- 场景 5：默认 L2 ----
+{
+  const { body } = renderSpec({ topic: 't' });
+  check('S5 默认级别 L2', /级别:\s*L2/.test(body.match(/^---([\s\S]*?)---/)[1]));
+}
+
+// ---- 场景 6：日期透传 ----
+{
+  const { body } = renderSpec({ topic: 't', date: '2026-12-31' });
+  check('S6 自定义日期透传', body.includes('日期: 2026-12-31'));
+}
+
+// ---- 场景 7：L3 必填提示独立复核 ----
+{
+  const { body } = renderSpec({ topic: 't', level: 'L3' });
+  check('S7 L3 节确认与复核含独立复核提示', body.includes('L3 必须独立复核'));
+}
+
+console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
+process.exit(failCount ? 1 : 0);

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

@@ -0,0 +1,192 @@
+// flow-kit gate-checklist：三处口径一致性检查（doctor §检查项 ↔ check-loop §检查项，显式配对登记表）
+// 目的：任何一处加新检查项，另一处不会自动同步——本工具按登记表给出对照表 + 断档/未登记告警。
+// 机制（2026-09-25 gate-checklist-registry 重写）：关键词猜测匹配退役（实测 18×14 项只匹配 2、报 28 条
+//       噪声缺点，真漏点不可见），改为显式配对登记表 PAIRS（单源本文件）——沿 workflow-modules.txt
+//       的单源思路与 check-loop「frontmatter 受限子集替代全文正则猜测」同一演进路径。
+// 解析面（只读不改两处源码，均为既有稳定结构）：
+//   doctor：src/doctor.mjs 节注释 `// N. 标题`（N 支持 6.5 小节号）
+//   check-loop：.agents/scripts/check-loop.sh 头部检查项注释 `# N. 标题 [severity]`（多行标题截断仅影响展示，配对按 id）
+// 登记三形态：
+//   { doctor, cl }        直接配对——同一检查两处实现
+//   { doctor, cl: null }  声明独有——doctor 装户体检面，无 check-loop 对应（原 intent「只报告不修复」拍板的已知漏点入账）
+//   { doctor: '7', cl }   经 §7 覆盖——doctor §7 整体运行 check-loop，各 #N 自动流入 doctor
+// 报告（只报告不修复，B-b；exit 恒 0）：
+//   断档：登记表声明的 id 在对应侧已不存在（检查项被删/改号而登记未跟）
+//   未登记：任一侧出现登记表之外的 § 检查项（新检查项没对账——本工具的核心信号）
+// 用法：node .agents/scripts/gate-checklist.mjs --diff
+//       node .agents/scripts/gate-checklist.mjs --json
+// 零依赖；不修改 doctor / check-loop 既有检查项
+// 测试：node templates/_agents/scripts/gate-checklist.test.mjs（fixture + 真实仓库 baseline）
+import fs from 'node:fs';
+import path from 'node:path';
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+// parseDoctorSections：扫 doctor.mjs 节注释 → [{id, title}]。两种真实格式：
+//   `// N. 标题`（整数节号带点，如 // 1. Node 版本）与 `// N.M 标题`（小节号不带点，如 // 6.5 delegations）。
+//   整数无点（如正文注释 // 4 宿主目录映射）不匹配——避免函数体普通注释误判为节。
+function parseDoctorSections(doctorSrc) {
+  const out = [];
+  const re = /^\s*\/\/\s+(\d+\.\d+|\d+\.)\s+([^\n]+)/gm;
+  let m;
+  while ((m = re.exec(doctorSrc)) !== null) {
+    const title = m[2].split(/[（(]/)[0].trim() || m[2].trim();
+    out.push({ id: m[1].replace(/\.$/, ''), title });
+  }
+  return out;
+}
+
+// parseCheckLoopChecks：扫 check-loop 检查项注释（`// N. 标题 [severity]` 于 .mjs 头部清单——2026-09-26
+// check-loop-node 迁移后的主位；旧装户 sync 前只有 .sh 时按 `# N. 标题` fallback，登记表口径不变）
+function parseCheckLoopChecks(clSrc) {
+  const checks = [];
+  const re = /^\s*(?:\/\/|#)\s*(\d+)\.\s+(.+?)(?:\s*\[(hard-block|warning|advisory)\])?\s*$/gm;
+  let m;
+  while ((m = re.exec(clSrc)) !== null) {
+    checks.push({ id: m[1], title: m[2].trim(), severity: m[3] || null });
+  }
+  return checks;
+}
+
+// ---- 配对登记表（单源契约；2026-09-25 gate-checklist-registry 全量登记）----
+// 纪律：doctor / check-loop 任一处加新 § 检查项，必须同步在本表登记（直接配对 / 声明独有 / 经 §7 覆盖），
+//       否则工具报「未登记」。删/改检查项须同步改本表，否则报「断档」。
+const PAIRS = [
+  // 直接配对：同一检查两处实现
+  { doctor: '5', cl: '2', note: '占位符残留' },
+  { doctor: '6', cl: '11', note: 'workflow/INDEX.md 漂移' },
+  // 声明独有：doctor 装户体检面（原 intent 拍板「只报告不修复」的已知漏点入账）
+  { doctor: '1', cl: null, note: 'Node 版本——装户体检独有' },
+  { doctor: '2', cl: null, note: '目录布局——装户体检独有' },
+  { doctor: '3', cl: null, note: 'git 仓库与钩子——装户体检独有' },
+  { doctor: '4', cl: null, note: 'kit.json managed 台账——装户体检独有' },
+  { doctor: '6.5', cl: null, note: 'delegations 台账结构——装户体检独有' },
+  { doctor: '6.6', cl: null, note: 'owned 漂移——装户体检独有' },
+  { doctor: '6.7', cl: null, note: '跨宿主薄适配——装户体检独有' },
+  { doctor: '6.8', cl: null, note: 'workflows 编排脚本 lint——装户体检独有' },
+  { doctor: '8', cl: null, note: '看板端口——信息级独有' },
+  // 经 §7 覆盖：doctor §7 整体运行 check-loop（#2/#11 已直接配对，不重复登记）
+  { doctor: '7', cl: '1', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '3', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '4', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '5', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '6', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '7', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '8', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '9', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '10', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '12', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '13', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '14', note: '经 §7 整体运行覆盖' },
+];
+
+// gateChecklist：按登记表对照两侧检查项（pure function；pairs 可注入供测试）
+// 返回 { doctorCount, checkLoopCount, pairs, matched, broken, unregistered, doctor, checkLoop }
+//   matched       = 登记两侧都存在的条目（直接配对 + 经 §7 覆盖）
+//   broken        = 登记声明的 id 在对应侧已不存在
+//   unregistered  = 两侧出现登记表之外的 § 检查项（新检查项未对账——核心信号）
+export function gateChecklist({ doctorSrc, checkLoopSrc, pairs = PAIRS }) {
+  const doctor = parseDoctorSections(doctorSrc);
+  const checkLoop = parseCheckLoopChecks(checkLoopSrc);
+  const doctorIds = new Set(doctor.map((d) => d.id));
+  const clIds = new Set(checkLoop.map((c) => c.id));
+  const declaredDoctor = new Set(pairs.map((p) => p.doctor).filter(Boolean));
+  const declaredCl = new Set(pairs.map((p) => p.cl).filter(Boolean));
+
+  const broken = [];
+  for (const p of pairs) {
+    if (p.doctor && !doctorIds.has(p.doctor)) broken.push({ side: 'doctor', id: p.doctor, note: p.note || '' });
+    if (p.cl && !clIds.has(p.cl)) broken.push({ side: 'check-loop', id: p.cl, note: p.note || '' });
+  }
+  const unregistered = [];
+  for (const d of doctor) {
+    if (!declaredDoctor.has(d.id)) unregistered.push({ side: 'doctor', id: d.id, title: d.title });
+  }
+  for (const c of checkLoop) {
+    if (!declaredCl.has(c.id)) unregistered.push({ side: 'check-loop', id: c.id, title: c.title });
+  }
+  const matched = pairs.filter((p) => p.doctor && doctorIds.has(p.doctor) && p.cl && clIds.has(p.cl));
+  return {
+    doctorCount: doctor.length,
+    checkLoopCount: checkLoop.length,
+    pairs,
+    matched,
+    broken,
+    unregistered,
+    doctor,
+    checkLoop,
+  };
+}
+
+const clip = (s, n) => (String(s).length > n ? String(s).slice(0, n) + '…' : String(s));
+
+function printDiff(result) {
+  console.log('▶ flow-kit gate-checklist --diff（显式配对登记表）');
+  const direct = result.pairs.filter((p) => p.doctor !== '7' && p.cl).length;
+  const via = result.pairs.filter((p) => p.doctor === '7').length;
+  const solo = result.pairs.filter((p) => !p.cl).length;
+  console.log(`  doctor §检查项: ${result.doctorCount}  |  check-loop §检查项: ${result.checkLoopCount}  |  直接配对 ${direct} + 经 §7 覆盖 ${via} + 声明独有 ${solo}`);
+  const doctorById = new Map(result.doctor.map((d) => [d.id, d]));
+  const clById = new Map(result.checkLoop.map((c) => [c.id, c]));
+  console.log('  对照表（登记表展开）:');
+  for (const p of result.pairs) {
+    const d = doctorById.get(p.doctor);
+    if (!p.cl) {
+      console.log(`    ● §${p.doctor} ${clip(d?.title || '?', 22)}（声明独有：${p.note}）`);
+    } else {
+      const c = clById.get(p.cl);
+      const mark = d && c ? '✓' : '✗';
+      console.log(`    ${mark} §${p.doctor} ${clip(d?.title || '?', 22)} ↔ #${p.cl} ${clip(c?.title || '?', 26)}（${p.note}）`);
+    }
+  }
+  if (result.broken.length) {
+    console.log('  断档（登记的检查项已不存在——删/改检查项后登记表未跟）:');
+    for (const b of result.broken) {
+      console.log(`    ⚠️  ${b.side === 'doctor' ? 'doctor §' + b.id : 'check-loop #' + b.id} 已不存在（登记备注：${b.note || '无'}）`);
+    }
+  }
+  if (result.unregistered.length) {
+    console.log('  未登记（新检查项未对账——配对 / 声明独有 / 经 §7 三选一登记进 PAIRS）:');
+    for (const u of result.unregistered) {
+      console.log(`    ⚠️  ${u.side === 'doctor' ? 'doctor §' + u.id : 'check-loop #' + u.id} ${clip(u.title, 30)}`);
+    }
+  }
+  if (!result.broken.length && !result.unregistered.length) {
+    console.log('  ✅ 登记完整（0 断档 / 0 未登记）');
+  }
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('gate-checklist.mjs');
+if (isMain) {
+  let jsonMode = false;
+  for (const a of process.argv.slice(2)) {
+    if (a === '--json') jsonMode = true;
+    else if (a === '--diff') { /* 默认模式，兼容显式传参 */ }
+    else fail('未知选项：' + a + '（flow-kit gate-checklist --diff / --json）');
+  }
+  const pkgRoot = process.argv[2] && !process.argv[2].startsWith('--') ? process.argv[2] : null;
+  const base = pkgRoot || process.cwd();
+  const doctorPath = path.join(base, 'src', 'doctor.mjs');
+  const clPathMjs = path.join(base, '.agents', 'scripts', 'check-loop.mjs');
+  const clPath = fs.existsSync(clPathMjs) ? clPathMjs : path.join(base, '.agents', 'scripts', 'check-loop.sh');
+  if (!fs.existsSync(doctorPath)) fail('找不到 doctor.mjs：' + doctorPath);
+  if (!fs.existsSync(clPath)) fail('找不到 check-loop（.mjs / .sh 均无）：' + clPath);
+  const doctorSrc = fs.readFileSync(doctorPath, 'utf8');
+  const checkLoopSrc = fs.readFileSync(clPath, 'utf8');
+  const result = gateChecklist({ doctorSrc, checkLoopSrc });
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({
+      doctorCount: result.doctorCount,
+      checkLoopCount: result.checkLoopCount,
+      matched: result.matched.map((p) => ({ doctor: p.doctor, cl: p.cl, note: p.note || '' })),
+      solo: result.pairs.filter((p) => !p.cl).map((p) => ({ doctor: p.doctor, note: p.note || '' })),
+      broken: result.broken,
+      unregistered: result.unregistered,
+    }, null, 2) + '\n');
+  } else {
+    printDiff(result);
+  }
+  // diff/json 模式总 exit 0；断档/未登记不视作错误（人类阅读用；B-b 决策「只报告不修复」）
+  process.exit(0);
+}
+export default gateChecklist;

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

@@ -0,0 +1,204 @@
+// gate-checklist.test.mjs — 显式配对登记表测试（2026-09-25 gate-checklist-registry）
+// 方法：fixture mini doctor.mjs / check-loop.sh 源码 + 注入 pairs，调 gateChecklist() 拿结构化结果；
+//       真实仓库两场景做 baseline；--json CLI spawn 冒烟回归原「字段丢失」bug。
+// 判据：① 两侧解析正确 ② 三种登记形态不误报 ③ 断档/未登记检测命中 ④ 真实仓库 0 断档 0 未登记
+// 用法：node templates/_agents/scripts/gate-checklist.test.mjs（npm test 随跑）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { gateChecklist } from './gate-checklist.mjs';
+
+let pass = 0;
+let failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log('PASS ' + name); }
+  else { failCount++; console.log('FAIL ' + name + (detail ? '——' + detail : '')); }
+}
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SRC_ROOT = path.resolve(SCRIPT_DIR, '..', '..', '..');
+
+// fixture：5 节 doctor（1 / 5 / 6.5 / 7 / 9）+ 2 项 check-loop（#2 / #3）
+const FIXTURE_DOCTOR = `// doctor fixture
+function f() {
+  // 1. Node 版本（装户体检独有）
+  const a = 1;
+  // 5. 占位符残留（与 check-loop #2 直接配对）
+  const b = 2;
+  // 6.5 delegations 台账结构（小节号解析）
+  const c = 3;
+  // 7. check-loop（fixture 里也有 §7，供经 §7 覆盖登记）
+  const e = 5;
+  // 9. 未登记的新检查项（应报未登记）
+  const d = 4;
+  return [a, b, c, d, e];
+}
+`;
+const FIXTURE_CL = `#!/bin/sh
+# 2. 模板字段占位符残留 [warning]
+# 3. incidents 复盘三件套完整性
+# 7. 未登记的新检查项
+exit 0
+`;
+// fixture 登记表：5↔2 直接配对、1 声明独有、6.5 声明独有、7→#3 经 §7 覆盖；
+// §99 / #99 是登记了但两侧都不存在的 id（应报断档×2）
+const FIXTURE_PAIRS = [
+  { doctor: '5', cl: '2', note: '占位符' },
+  { doctor: '1', cl: null, note: '独有' },
+  { doctor: '6.5', cl: null, note: '独有' },
+  { doctor: '7', cl: '3', note: '经 §7' },
+  { doctor: '99', cl: null, note: '断档——doctor 侧不存在' },
+  { doctor: '1', cl: '99', note: '断档——check-loop 侧不存在' },
+];
+
+const run = (pairs = FIXTURE_PAIRS, doctorSrc = FIXTURE_DOCTOR, clSrc = FIXTURE_CL) =>
+  gateChecklist({ doctorSrc, checkLoopSrc: clSrc, pairs });
+
+// ---- S1 解析：doctor 5 节（含 6.5 小节号、§7 与未登记的 9）----
+{
+  const r = run();
+  check('S1 fixture doctor 解析 5 节且含 6.5 小节号',
+    r.doctorCount === 5 && r.doctor.some((d) => d.id === '6.5' && d.title.includes('delegations')),
+    JSON.stringify(r.doctor));
+}
+
+// ---- S2 解析：check-loop 3 项（#2 带 severity，#3 无）----
+{
+  const r = run();
+  const c2 = r.checkLoop.find((c) => c.id === '2');
+  const c3 = r.checkLoop.find((c) => c.id === '3');
+  check('S2 fixture check-loop 解析 3 项且 severity 提取正确',
+    r.checkLoopCount === 3 && c2.severity === 'warning' && c3.severity === null,
+    JSON.stringify(r.checkLoop));
+}
+
+// ---- S3 直接配对：5↔2 双侧存在 → matched 命中 ----
+{
+  const r = run();
+  check('S3 直接配对 §5↔#2 进入 matched',
+    r.matched.some((p) => p.doctor === '5' && p.cl === '2'),
+    JSON.stringify(r.matched.map((p) => [p.doctor, p.cl])));
+}
+
+// ---- S4 声明独有：§1 / §6.5 不产生任何 findings ----
+{
+  const r = run();
+  const hit = [...r.broken, ...r.unregistered].filter((f) => f.id === '1' || f.id === '6.5');
+  check('S4 声明独有（§1 / §6.5）不误报',
+    hit.length === 0,
+    JSON.stringify(hit));
+}
+
+// ---- S5 经 §7 覆盖：7→#3 不产生 findings 且进 matched ----
+{
+  const r = run();
+  check('S5 经 §7 覆盖登记不误报且进 matched',
+    r.matched.some((p) => p.doctor === '7' && p.cl === '3') && !r.unregistered.some((u) => u.id === '3'),
+    JSON.stringify(r.unregistered));
+}
+
+// ---- S6 断档：登记 §99 / #99 两侧不存在 → broken ×2 ----
+{
+  const r = run();
+  const bDoc = r.broken.find((b) => b.side === 'doctor' && b.id === '99');
+  const bCl = r.broken.find((b) => b.side === 'check-loop' && b.id === '99');
+  check('S6 登记断档两侧各报一条（doctor §99 / check-loop #99）',
+    r.broken.length === 2 && !!bDoc && !!bCl,
+    JSON.stringify(r.broken));
+}
+
+// ---- S7 未登记：doctor §9 与 check-loop #7 → unregistered ×2 ----
+{
+  const r = run();
+  const uDoc = r.unregistered.find((u) => u.side === 'doctor' && u.id === '9');
+  const uCl = r.unregistered.find((u) => u.side === 'check-loop' && u.id === '7');
+  check('S7 未登记两侧各报一条（doctor §9 / check-loop #7）',
+    r.unregistered.length === 2 && !!uDoc && !!uCl,
+    JSON.stringify(r.unregistered));
+}
+
+// ---- S8 空源码 + 空登记表不崩（0 findings）----
+{
+  const r = run([], '', '');
+  check('S8 空源码 + 空登记表不崩（0/0 且 0 findings）',
+    r.doctorCount === 0 && r.checkLoopCount === 0 && r.broken.length === 0 && r.unregistered.length === 0,
+    JSON.stringify(r));
+}
+
+// ---- S8b 整数无点注释不误判为节（doctor.mjs:257 // 4 宿主目录映射 形态）----
+{
+  const doctorSrc = `// 4. kit.json managed 台账（真节）
+const x = 1;
+  // 4 宿主目录映射（与 profiles 同源——正文注释，非节）
+const y = 2;
+`;
+  const r = gateChecklist({ doctorSrc, checkLoopSrc: '', pairs: [{ doctor: '4', cl: null, note: '独有' }] });
+  check('S8b 整数无点的正文注释不误判（仅解析 1 节 §4 且标题为真节）',
+    r.doctorCount === 1 && r.doctor[0].title.includes('kit.json') && r.broken.length === 0 && r.unregistered.length === 0,
+    JSON.stringify(r.doctor));
+}
+
+// ---- S9 重复 id 登记（同 cl 两个直接配对）不崩且均可命中 ----
+{
+  const pairs = [
+    { doctor: '5', cl: '2', note: 'a' },
+    { doctor: '1', cl: '2', note: 'b' },
+  ];
+  const r = run(pairs);
+  check('S9 多条目登记同一 cl 不崩（matched 2）',
+    r.matched.length === 2 && r.unregistered.some((u) => u.side === 'check-loop' && u.id === '3'),
+    JSON.stringify({ m: r.matched.length, u: r.unregistered }));
+}
+
+const realDoctor = () => fs.readFileSync(path.join(SRC_ROOT, 'src', 'doctor.mjs'), 'utf8');
+// check-loop 解析面与 CLI 同口径：.mjs 优先（2026-09-26 迁移后主位），fallback .sh（旧装户）
+const realCl = () => {
+  const mjs = path.join(SRC_ROOT, '.agents', 'scripts', 'check-loop.mjs');
+  return fs.readFileSync(fs.existsSync(mjs) ? mjs : path.join(SRC_ROOT, '.agents', 'scripts', 'check-loop.sh'), 'utf8');
+};
+const hasReal = fs.existsSync(path.join(SRC_ROOT, 'src', 'doctor.mjs'));
+
+// ---- S10 真实仓库 baseline：PAIRS 全量登记 → 0 断档 / 0 未登记 ----
+if (hasReal) {
+  const r = gateChecklist({ doctorSrc: realDoctor(), checkLoopSrc: realCl() });
+  check('S10 真实仓库登记完整（0 断档 / 0 未登记）',
+    r.broken.length === 0 && r.unregistered.length === 0,
+    JSON.stringify({ broken: r.broken, unregistered: r.unregistered }));
+}
+
+// ---- S11 真实仓库计数：doctor ≥ 12 节 / check-loop ≥ 14 项 ----
+if (hasReal) {
+  const r = gateChecklist({ doctorSrc: realDoctor(), checkLoopSrc: realCl() });
+  check('S11 真实仓库 doctor ≥ 12 节且 check-loop ≥ 14 项（baseline）',
+    r.doctorCount >= 12 && r.checkLoopCount >= 14,
+    `doctor ${r.doctorCount} / check-loop ${r.checkLoopCount}`);
+}
+
+// ---- S12 --json CLI 冒烟：键齐无 undefined（回归原 .title 字段丢失 bug）----
+if (hasReal) {
+  const p = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'gate-checklist.mjs'), '--json'], { cwd: SRC_ROOT, encoding: 'utf8' });
+  let j = null;
+  try { j = JSON.parse(p.stdout); } catch { /* fail below */ }
+  const keysOk = j && ['doctorCount', 'checkLoopCount', 'matched', 'solo', 'broken', 'unregistered'].every((k) => k in j);
+  const noHoles = j && JSON.stringify(j).includes('undefined') === false
+    && j.matched.every((m) => typeof m.doctor === 'string' && typeof m.cl === 'string' && 'note' in m);
+  check('S12 --json 可解析、键齐、条目无 undefined 丢字段、exit 0',
+    p.status === 0 && !!keysOk && !!noHoles,
+    String(p.stdout).slice(0, 200));
+}
+
+// ---- S13 doctor 多行节注释：首行即标题（6.6 形态）解析不漏 ----
+{
+  const doctorSrc = `// 6.6 owned 漂移校验（kit.owned 列表盘面 sha 不一致；
+//     漂移信号靠本校验给装户可见性）
+const x = 1;
+`;
+  const r = gateChecklist({ doctorSrc, checkLoopSrc: '', pairs: [{ doctor: '6.6', cl: null, note: '独有' }] });
+  check('S13 多行节注释（§6.6 形态）首行命中且登记不报 findings',
+    r.doctorCount === 1 && r.doctor[0].title.includes('owned') && r.broken.length === 0 && r.unregistered.length === 0,
+    JSON.stringify(r.doctor));
+}
+
+console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
+process.exit(failCount ? 1 : 0);

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

@@ -10,6 +10,7 @@
 // 生成区：INDEX.md 的 GENERATED:BEGIN/END 锚点注释之间整段重写，锚点外内容原样保留。
 import fs from 'node:fs';
 import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
 
 const USAGE = `用法：node .agents/scripts/gen-workflow-index.mjs [--dry-run] [--check] [--help]
 
@@ -32,14 +33,15 @@ const WORKFLOW = 'workflow';
 const INDEX_P = path.join(WORKFLOW, 'INDEX.md');
 const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
 const TYPE_LABEL = { intents: 'INTENT', specs: 'SPEC', plans: 'PLAN', incidents: 'INCIDENT' };
-const ACTIVE_STATUS = ['draft', 'approved', 'open']; // 其余（done/fixed/closed/superseded/cancelled）折叠进档案计数
+// 活跃口径 = 单源 doc.status.active ∪ incident.status.active；其余状态折叠进档案计数
+const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 
 const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-index.mjs 整段重写，手工说明写在本行之前 -->';
 const END = '<!-- GENERATED:END -->';
 const HEADER = `# workflow 索引 — 活跃层与档案（生成物，勿手改）
 
 > 生成器 \`node .agents/scripts/gen-workflow-index.mjs\`（状态变更 / 新建文档后重跑；\`--check\` 校验漂移，check-loop 会告警）。
-> 活跃 = draft / approved / open（在跑）；其余状态折叠进档案计数，检索用 \`node .agents/scripts/kb-search.mjs "<词>"\`（默认含全部状态、活跃优先排序）。
+> 活跃 = ${ACTIVE_STATUS.join(' / ')}（在跑）；其余状态折叠进档案计数，检索用 \`node .agents/scripts/kb-search.mjs "<词>"\`（默认含全部状态、活跃优先排序）。
 > 模块词表见 \`.agents/workflow-modules.txt\`。
 `;
 

package/templates/_agents/scripts/kb-search.mjs

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { ENUMS } from './workflow-enums.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const MODULES_FILE = path.join(SCRIPT_DIR, '..', 'workflow-modules.txt');
@@ -78,7 +79,8 @@ if (moduleFilter && !MODULES.includes(moduleFilter)) {
   process.exit(1);
 }
 
-const ACTIVE_STATUS = ['draft', 'approved', 'open']; // 与 workflow/INDEX.md 活跃口径一致（fixed 归档案，默认也可命中）
+// 活跃口径 = 单源 doc.status.active ∪ incident.status.active（与 workflow/INDEX.md 活跃层一致，fixed 归档案默认也可命中）
+const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const WF_SECTIONS = ['背景', '目标', '根因', '复盘三件套', '验收标准', '影响面'];
 const WIKI_EXCLUDE = new Set(['INDEX.md', '知识沉淀总览.html']);
 const WIKI_MAX_KB = 180;