agentic-flow-kit 0.4.0 → 0.5.0

package/templates/_agents/scripts/workflow-enums.test.mjs

@@ -0,0 +1,110 @@
+// workflow-enums.test.mjs — 枚举单源读取器测试（2026-09-25 enum-single-source）
+// 判据：① 真实单源文件解析 + 不变量通过 ② 坏数据（坏行/重复键/重复值/缺键/子集破/重叠）fail-loud
+//       ③ 缺文件 fail-loud ④ sh 消费方同口径（sed 可取到全部 8 键）
+// 用法：node templates/_agents/scripts/workflow-enums.test.mjs（npm test 随跑）
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseEnums, validateEnums, loadEnums, ENUMS } from './workflow-enums.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+const throwsWith = (fn, kw) => {
+  try { fn(); return false; } catch (e) { return String(e.message).includes(kw); }
+};
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ENUMS_TXT = path.join(SCRIPT_DIR, '..', 'workflow-enums.txt');
+
+// ---- S1 模块级 ENUMS 即加载即校验（真实文件），8 键齐 ----
+{
+  const keys = Object.keys(ENUMS).sort();
+  check('S1 真实单源文件加载成功且 8 键齐',
+    keys.length === 8 && keys.join(',') === 'doc.status.abandoned,doc.status.active,doc.status.all,doc.status.confirmed,doc.status.terminal,incident.status.active,incident.status.all,level.all',
+    JSON.stringify(keys));
+}
+
+// ---- S2 真实文件关键值口径（check-loop/看板/检索的行为锚点，值变更须连本测试一起改）----
+{
+  check('S2 关键集值口径：confirmed 不含 draft、active=draft+approved、terminal 含 done、abandoned ⊆ terminal',
+    !ENUMS['doc.status.confirmed'].includes('draft')
+      && ENUMS['doc.status.active'].join('+') === 'draft+approved'
+      && ENUMS['doc.status.terminal'].includes('done')
+      && ENUMS['doc.status.abandoned'].every((v) => ENUMS['doc.status.terminal'].includes(v))
+      && ENUMS['level.all'].length === 4,
+    JSON.stringify(ENUMS));
+}
+
+// ---- S3 坏行 fail-loud ----
+{
+  check('S3 非法行抛错', throwsWith(() => parseEnums('乱行 no-equals-sign'), '行格式非法'));
+}
+
+// ---- S4 重复键 fail-loud ----
+{
+  check('S4 重复键抛错', throwsWith(() => parseEnums('a.b=x\na.b=y'), '键重复'));
+}
+
+// ---- S5 重复值 fail-loud ----
+{
+  check('S5 重复值抛错', throwsWith(() => parseEnums('a.b=x x'), '值重复'));
+}
+
+// ---- S6 缺键 fail-loud（validateEnums）----
+{
+  check('S6 缺键抛错', throwsWith(() => validateEnums({ 'level.all': ['L0'] }), '缺键'));
+}
+
+// ---- S7 子集破 fail-loud ----
+{
+  const bad = {
+    'doc.status.all': ['draft', 'approved', 'done'], 'doc.status.confirmed': ['approved', 'done', 'ghost'],
+    'doc.status.active': ['draft'], 'doc.status.terminal': ['done'], 'doc.status.abandoned': ['cancelled'],
+    'incident.status.all': ['open'], 'incident.status.active': ['open'], 'level.all': ['L0'],
+  };
+  check('S7 子集不变量破抛错', throwsWith(() => validateEnums(bad), '不变量破'));
+}
+
+// ---- S8 活跃/终态重叠 fail-loud ----
+{
+  const bad = Object.fromEntries(Object.entries(ENUMS).map(([k]) => [k, [...ENUMS[k]]]));
+  bad['doc.status.terminal'] = [...bad['doc.status.terminal'], 'draft'];
+  check('S8 active 与 terminal 重叠抛错', throwsWith(() => validateEnums(bad), '重叠'));
+}
+
+// ---- S9 缺文件 fail-loud（loadEnums）----
+{
+  check('S9 单源文件缺失抛错（fail-loud 无 fallback）',
+    throwsWith(() => loadEnums(path.join(SCRIPT_DIR, '..', 'no-such-enums.txt')), '不可读'));
+}
+
+// ---- S10 注释行与空行忽略 ----
+{
+  const e = parseEnums('# 注释\n\nlevel.all=L0 L1\n');
+  check('S10 注释与空行忽略（仅 1 键）', Object.keys(e).length === 1 && e['level.all'].join('+') === 'L0+L1');
+}
+
+// ---- S11 sh 消费方同口径：check-loop.sh 的 sed 取法能取到全部 8 键 ----
+{
+  const key = 'doc.status.confirmed';
+  const val = execSync(`sh -c "sed -n 's/^${key}=//p' '${ENUMS_TXT}' | head -n 1"`, { encoding: 'utf8' }).trim();
+  check('S11 sh sed 取键与 node 读取同值（跨语言单源口径）',
+    val === ENUMS[key].join(' '), `sh=[${val}] node=[${ENUMS[key].join(' ')}]`);
+}
+
+// ---- S12 CRLF 行尾容忍（autocrlf 检出坑：rule-budgets.txt 同约定；node 侧 split(/\r?\n/) 天然免疫，显式锁定）----
+{
+  const crlf = 'doc.status.all=draft approved done superseded cancelled\r\nlevel.all=L0 L1 L2 L3\r\n';
+  const e = parseEnums(crlf);
+  check('S12 CRLF 行尾不残留 \\r（值尾无回车）',
+    e['level.all'].join('+') === 'L0+L1+L2+L3' && !e['doc.status.all'].some((v) => v.includes('\r')),
+    JSON.stringify(e));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/workflows-check.mjs

@@ -0,0 +1,260 @@
+// flow-kit workflows-check：编排脚本机器 lint（2026-09-25 workflows-linter，审查改进方向 1）
+// 目的：`.agents/workflows/_TEMPLATE.md`「解析校验先行」此前是纯 prose——role ∈ .agents/roles/、
+//       step ∈ steps/、after 引用存在且无环，全靠宿主 AI 自觉；而编排脚本的书写者与执行者是同一
+//       宿主 AI，缺外部裁决者。本工具把该纪律变成机器门：解析 .agents/workflows/*.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/workflows/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()（doctor 以 cwd=target 调用；仓库根直跑即自扫）
+// 零依赖；只报告不修复（B-b 决策口径，同 source-sync-check）
+// 测试：node templates/_agents/scripts/workflows-check.test.mjs（fixture + 真实仓库 baseline）
+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/workflows/（pure function，测试/doctor 共用）
+// 返回 { root, roles, steps, files: [{file, errors, warnings}], errorCount, warningCount }
+export function lintWorkflows({ root }) {
+  const wfRoot = path.join(root, '.agents', 'workflows');
+  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('▶ flow-kit workflows-check（.agents/workflows/ 编排脚本 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}（flow-kit 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/_agents/scripts/workflows-check.test.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// workflows-check.test.mjs — 编排脚本 lint 测试（2026-09-25 workflows-linter）
+// 方法：fixture 临时目录（.agents/workflows/*.md + roles/ + steps/ 词表）调 lintWorkflows() 拿结构化结果，
+//       不依赖真实仓库文件；末两个场景对真实仓库自扫做 baseline 断言。
+// 判据：error 10 类各至少一场景命中；advisory 3 类各一场景；_ 前缀排除；真实仓库 0 error。
+// 用法：node templates/_agents/scripts/workflows-check.test.mjs（npm test 随跑）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lintWorkflows } from './workflows-check.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+
+const HEAD = '| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | retries |';
+const SEP = '|----|-------|------|------|---------------|--------------|-------------------|------|---------|';
+
+// mkfix：建临时根 + 词表（roles: implementer/reviewer；steps: deploy）+ 指定编排脚本集合
+const mkfix = (scripts) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'wf-lint-test-'));
+  fs.mkdirSync(path.join(root, '.agents', 'workflows', 'steps'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents', 'roles'), { recursive: true });
+  for (const r of ['implementer', 'independent-reviewer']) {
+    fs.writeFileSync(path.join(root, '.agents', 'roles', `${r}.md`), `# ${r}\n`);
+  }
+  fs.writeFileSync(path.join(root, '.agents', 'workflows', 'steps', 'deploy.md'), '# deploy\n');
+  for (const [name, body] of Object.entries(scripts)) {
+    fs.writeFileSync(path.join(root, '.agents', 'workflows', name), body);
+  }
+  return root;
+};
+const fm = (extra = '') => `---\nname: t\ndescription: t\n${extra}---\n\n# w\n\n`;
+
+// ---- S1 全绿：双 role 并行 + 汇聚 gate → 0 error 0 warning ----
+{
+  const root = mkfix({
+    'ok.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | implementer | — | 做 A | src/a/** | 测试过 | | 1 |\n' +
+      '| b | — | implementer | — | 做 B | src/b/** | 构建过 | | 0 |\n' +
+      '| g | a,b | — | — | — | — | — | npm test | |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S1 全绿（并行 role + 汇聚 gate）→ 0 error 0 warning',
+    r.errorCount === 0 && r.warningCount === 0 && r.files.length === 1,
+    JSON.stringify(r.files[0]));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S2 after 悬空引用 → E5 ----
+{
+  const root = mkfix({
+    'dangling.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | ghost | — | — | — | — | — | npm test | |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S2 after 引用不存在 → E5',
+    r.errorCount === 1 && r.files[0].errors[0].startsWith('E5') && r.files[0].errors[0].includes('ghost'),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S3 after 成环 → E6 ----
+{
+  const root = mkfix({
+    'cycle.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | b | — | — | — | — | — | npm test | |\n' +
+      '| b | a | — | — | — | — | — | npm test | |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S3 after 依赖成环 → E6',
+    r.errorCount === 1 && r.files[0].errors[0].startsWith('E6'),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S4 未知 role → E7（词表只有 implementer / independent-reviewer）----
+{
+  const root = mkfix({
+    'role.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | hacker | — | 做 A | src/** | 过 | | |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S4 role 不在 .agents/roles/ → E7',
+    r.errorCount === 1 && r.files[0].errors[0].startsWith('E7') && r.files[0].errors[0].includes('hacker'),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S5 未知 step → E8（steps/ 只有 deploy）----
+{
+  const root = mkfix({
+    'step.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | — | rollback | env=prod | | exit 0 | | 0 |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S5 step 不在 steps/ → E8',
+    r.errorCount === 1 && r.files[0].errors[0].startsWith('E8') && r.files[0].errors[0].includes('rollback'),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S6 三形态全空 / 双填 → E9 ×2 ----
+{
+  const root = mkfix({
+    'forms.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| nothing | — | — | — | 只有任务没有形态 | src/** | 过 | | |\n' +
+      '| both | — | implementer | deploy | 形态双填 | src/** | 过 | npm test | |\n',
+  });
+  const r = lintWorkflows({ root });
+  const e9 = r.files[0].errors.filter((e) => e.startsWith('E9'));
+  check('S6 三形态全空与双填 → E9 ×2',
+    r.errorCount === 2 && e9.length === 2 && e9[0].includes('nothing') && e9[1].includes('both'),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S7 retries 非法 / concurrency 非法 → E10 + E2 ----
+{
+  const root = mkfix({
+    'nums.md': fm('concurrency: x\n') + HEAD + '\n' + SEP + '\n' +
+      '| a | — | — | — | — | — | — | npm test | 重试 |\n',
+  });
+  const r = lintWorkflows({ root });
+  const codes = r.files[0].errors.map((e) => (e.match(/^E\d+/) || [''])[0]);
+  check('S7 retries 非数字 → E10 且 concurrency 非法 → E2',
+    r.errorCount === 2 && codes.includes('E10') && codes.includes('E2'),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S8 gate 花括号展开 → W1（0 error，advisory）----
+{
+  const root = mkfix({
+    'brace.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| g | — | — | — | — | — | — | node scripts/fill-{intent,plan}.test.mjs | |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S8 gate 含 {a,b} 花括号展开 → W1 且不计 error',
+    r.errorCount === 0 && r.warningCount === 1 && r.files[0].warnings[0].startsWith('W1'),
+    JSON.stringify({ e: r.files[0].errors, w: r.files[0].warnings }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S9 授权文件交叉：无先序告警 / 有 after 先序不告警 ----
+{
+  const root = mkfix({
+    'parallel-cross.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | implementer | — | 做 A | src/shared/** | 过 | | |\n' +
+      '| b | — | implementer | — | 做 B | src/shared/** | 过 | | |\n',
+    'ordered-ok.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | implementer | — | 做 A | src/shared/** | 过 | | |\n' +
+      '| b | a | implementer | — | 做 B | src/shared/** | 过 | | |\n',
+  });
+  const r = lintWorkflows({ root });
+  const cross = r.files.find((f) => f.file === 'parallel-cross.md');
+  const ordered = r.files.find((f) => f.file === 'ordered-ok.md');
+  check('S9 授权文件相同且无先序 → W2；有 after 先序 → 不告警',
+    r.errorCount === 0 && cross.warnings.length === 1 && cross.warnings[0].startsWith('W2') && ordered.warnings.length === 0,
+    JSON.stringify({ cross: cross.warnings, ordered: ordered.warnings }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S10 _ 前缀机制文档不进扫描面（内含坏表也不报）----
+{
+  const root = mkfix({
+    '_TEMPLATE.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| bad | ghost | hacker | — | — | — | — | — | 重试 |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S10 _TEMPLATE.md 排除（机制文档含示例表，不按可执行件校验）',
+    r.files.length === 0 && r.errorCount === 0 && r.warningCount === 0,
+    JSON.stringify(r.files.map((f) => f.file)));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S11 缺 frontmatter → E1；缺 stages 表 → E3 ----
+{
+  const root = mkfix({
+    'nofm.md': '# 没有 frontmatter\n\n只有正文\n',
+    'notable.md': fm() + '# 有 frontmatter 没有 stages 表\n',
+  });
+  const r = lintWorkflows({ root });
+  const nofm = r.files.find((f) => f.file === 'nofm.md');
+  const notable = r.files.find((f) => f.file === 'notable.md');
+  check('S11 缺 frontmatter → E1 且缺表 → E3',
+    nofm.errors.some((e) => e.startsWith('E1')) && notable.errors.some((e) => e.startsWith('E3')),
+    JSON.stringify({ nofm: nofm.errors, notable: notable.errors }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S12 id 重复 → E4；id 空 → E4 ----
+{
+  const root = mkfix({
+    'dup.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | — | — | — | — | — | npm test | |\n' +
+      '| a | — | — | — | — | — | — | npm test | |\n' +
+      '| — | — | — | — | 缺 id 行 | — | — | — | |\n',
+  });
+  const r = lintWorkflows({ root });
+  const e4 = r.files[0].errors.filter((e) => e.startsWith('E4'));
+  check('S12 id 重复与缺 id → E4 ×2',
+    e4.length === 2 && e4.some((e) => e.includes('重复')) && e4.some((e) => e.includes('缺 id')),
+    JSON.stringify(r.files[0].errors));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S13 step 引用 + gate + 空值规范（— / 空 retries / 空 gate）混排全绿 ----
+{
+  const root = mkfix({
+    'mixed.md': fm('concurrency: 3\n') + HEAD + '\n' + SEP + '\n' +
+      '| build | — | implementer | — | 构建 | src/** | 测试过 | | |\n' +
+      '| verify | build | — | deploy | env=staging | | exit 0 | | 2 |\n' +
+      '| final | verify | — | — | — | — | — | npm test | |\n',
+  });
+  const r = lintWorkflows({ root });
+  check('S13 step 行 / gate 行 / em-dash 空值 / concurrency=3 / retries=2 混排全绿',
+    r.errorCount === 0 && r.warningCount === 0,
+    JSON.stringify(r.files[0]));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S14 真实仓库自扫 baseline：0 error（_TEMPLATE 排除后三份可执行件全过）----
+{
+  const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+  const r = lintWorkflows({ root: ROOT });
+  const names = r.files.map((f) => f.file).join('、');
+  check('S14 真实仓库 .agents/workflows/ 自扫 0 error（扫描面：' + names + '）',
+    r.errorCount === 0 && r.files.length >= 3,
+    JSON.stringify(r.files.filter((f) => f.errors.length).map((f) => ({ f: f.file, e: f.errors }))));
+}
+
+// ---- S14 human 确认门（第四形态）：单形态全绿 / 双填 E9 / ×retries W4 / 缺列兼容 ----
+{
+  const HEAD10 = '| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |';
+  const SEP10 = '|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|';
+  const root = mkfix({
+    'human-ok.md': fm() + HEAD10 + '\n' + SEP10 + '\n' +
+      '| a | — | implementer | — | 做 A | src/a/** | 测试过 | | | 0 |\n' +
+      '| ask | a | — | — | 用户确认可继续 | — | 一句「可以」 | | 用户确认 | |\n' +
+      '| b | ask | — | — | — | — | — | npm test | | |\n',
+    'human-bad.md': fm() + HEAD10 + '\n' + SEP10 + '\n' +
+      '| both | — | — | — | 双填 | — | — | npm test | 用户确认 | |\n' +
+      '| retry | — | — | — | 确认 | — | 一句可以 | | 用户确认 | 2 |\n',
+    'no-human-col.md': fm() + HEAD + '\n' + SEP + '\n' +
+      '| a | — | — | — | — | — | — | npm test | |\n',
+  });
+  const r = lintWorkflows({ root });
+  const ok = r.files.find((f) => f.file === 'human-ok.md');
+  const bad = r.files.find((f) => f.file === 'human-bad.md');
+  const legacy = r.files.find((f) => f.file === 'no-human-col.md');
+  check('S14 human 单形态 10 列全绿；human+gate 双填 E9；human×retries W4；9 列无 human 表全过',
+    r.errorCount === 1
+      && ok.errors.length === 0 && ok.warnings.length === 0
+      && bad.errors.length === 1 && bad.errors[0].startsWith('E9') && bad.errors[0].includes('gate + human')
+      && bad.warnings.length === 1 && bad.warnings[0].startsWith('W4')
+      && legacy.errors.length === 0 && legacy.warnings.length === 0,
+    JSON.stringify(r.files.map((f) => ({ f: f.file, e: f.errors, w: f.warnings }))));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/workflow-enums.txt

@@ -0,0 +1,19 @@
+# workflow 文档枚举单源（2026-09-25 enum-single-source）
+# 本文件会被 core.autocrlf 检出为 CRLF——读取方显式去 \r（check-loop enum_val / node parseEnums），禁止依赖行尾格式（rule-budgets.txt 同约定）。
+# 消费方：check-loop.sh / workflow-board-server.mjs / kb-search.mjs / gen-workflow-index.mjs /
+#         fill-{intent,plan,spec}.mjs（经 scripts/workflow-enums.mjs 读取器）——改枚举改这里，别改消费方。
+# 格式：key=value value value（空格分隔；# 注释行忽略；键重复 / 值重复 / 缺键 = 消费方 fail-loud）
+# 语义：doc = intent/spec/plan 三件；incident = 事故件。
+#   all       全生命周期状态
+#   confirmed 已确认（check-loop「状态未确认」放行口径 = 看板枚举告警口径）
+#   active    活跃（INDEX 活跃层 / kb-search 活跃 ×1.3 排序）
+#   terminal  终态（看板「入口已 done 而 plan 未终态」告警口径）
+#   abandoned 放弃留档（L3 确认三件豁免口径）
+doc.status.all=draft approved done superseded cancelled
+doc.status.confirmed=approved done superseded cancelled
+doc.status.active=draft approved
+doc.status.terminal=done superseded cancelled
+doc.status.abandoned=superseded cancelled
+incident.status.all=open fixed closed
+incident.status.active=open
+level.all=L0 L1 L2 L3