agentic-flow-kit 0.4.0 → 0.6.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（node parseEnums），禁止依赖行尾格式（rule-budgets.txt 同约定）。
+# 消费方：check-loop.mjs / 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

package/templates/_agents/workflows/_TEMPLATE.md

@@ -0,0 +1,75 @@
+# Workflow 编排机制 — 编排脚本 + steps 扩展点
+
+> kit 的跨宿主编排机制：`.agents/workflows/` 下的编排脚本承载编排语义（依赖分层 / 并行 / 重试 / gate / 用户确认门 / run journal），**宿主 AI 经 AGENTS.md 常驻指令自动加载并按语义执行**——有子智能体的宿主并行 fan-out，没有的顺序自做，验收不变。零宿主协议适配：机制只依赖所有宿主共有的四样本领（读 AGENTS.md、读仓库文件、跑终端命令、子智能体）。
+
+## 自动加载（AGENTS.md 常驻指令）
+
+> 多工作包编排——用户要跑编排、或 plan 执行多工作包时：读 `.agents/workflows/` 编排脚本按本文档语义执行；自定义步骤在 `steps/`。
+
+## 编排脚本（`.agents/workflows/<主题>.md`）
+
+frontmatter（`name` / `description` / `concurrency` 默认 2）+ 一张 stages 表（`human` 列可选——不用确认门的可省该列，保持 9 列）：
+
+```md
+---
+name: 并行修两域
+description: 后端+前端并行实现 → 汇聚过测试 → 部署验证（step）→ 独立评审
+concurrency: 2
+---
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| backend | — | implementer | — | 实现后端 X | src/api/** | 项目测试过 | | | 1 |
+| frontend | — | implementer | — | 改前端 Y | web/** | 构建过 | | | 0 |
+| gate-all | backend,frontend | — | — | — | — | — | npm test | | |
+| confirm-deploy | gate-all | — | — | 用户对话内确认可上 staging | — | 一句「可以」 | | 用户确认 | |
+| deploy-check | confirm-deploy | — | 部署验证 | env=staging | | 部署命令 exit 0 | | | 0 |
+| review | deploy-check | independent-reviewer | — | 评审两域改动 | | 符合 plan 与判据 | | | 0 |
+```
+
+**stage 四形态**（互斥，恰填一项）：
+
+| 形态 | 判据 | 执行 |
+|------|------|------|
+| role 派单行 | `role` 非空 | 派子智能体（`task` 目标 / `files` 授权清单 / `accept` 验收判据写进派单头 + 红线行） |
+| step 行 | `step` 非空 | 宿主 AI 读 `steps/<step>.md` 按指引执行，`task / params` 列传参 |
+| gate 行 | `gate` 非空（role/step/human 空） | 终端跑命令，非零即中止 |
+| human 确认门行 | `human` 非空（其余形态列空） | 宿主 AI **停下向用户询问**（`task` 列 = 问什么、`accept` 列 = 通过判据），通过才派下层；驳回 → 中止汇总。**不派子智能体**（机器判据层面落实「子智能体不跨确认门」，取代早前 role 行伪装确认门的写法） |
+
+**编排语义**（执行口径，全宿主同一）：`after` 空 = 第 0 层；一层全 ok 才派依赖它的下一层；层内按 `concurrency` 分批——有子智能体的宿主并行 fan-out，没有的顺序自做（验收标准不变）；失败且 `retries` > 0 → 重派（全新上下文）；重试超限 / gate 非零 / human 驳回 → 中止后续、汇总报告失败项。human 行无重试语义（retries 视作 0）。
+
+**run journal**（断点续跑与重试计量）：每个 stage 每次尝试出结果（pass / fail / blocked）即记一行；中止后重跑先看 status——已 pass 的 stage 不重跑，从就绪层续：
+
+```bash
+node .agents/scripts/wf-journal.mjs add --wf <编排名> --stage <id> --status pass --form human   # fail/blocked 同式；--form ∈ role|step|gate|human
+node .agents/scripts/wf-journal.mjs status --wf <编排名>                                        # 已完成 / 就绪（含重试就绪×N）/ 待定
+```
+
+journal 落 `.agents/cache/orchestration-runs.jsonl`（本地运行态，可丢弃；同 run 同 stage 多行按末次生效，attempt 自动计次；`--new-run` 新起一轮）。
+
+## steps 扩展点（`.agents/workflows/steps/<名>.md`）
+
+kit 定义的扩展机制：文件名即步骤名（steps 目录即注册表），项目把自己的领域动作（部署 / 迁移 / 审计上报…）注册进来，编排脚本 step 行引用即用。
+
+```md
+---
+params: env（目标环境）；timeout-min（可选，默认 10）
+---
+# 步骤 — 部署验证
+
+1. 跑终端命令：`npm run deploy -- --env <env>`，非零即步骤失败并回报 stderr 尾段
+2. 跑冒烟检查：`curl -fsS https://<env>.example.com/healthz`
+3. 回报：部署版本号 + 冒烟结果
+```
+
+- frontmatter `params`：参数约定（自由文本列明名称与含义）；调用方在编排脚本 `task / params` 列传参（`k=v`，空格分隔多个）。
+- 正文：执行指引（编号步骤）——可指使命令、子智能体、检查动作；步骤失败按编排脚本行 `retries` 重试。
+
+## 纪律（先读）
+
+- **声明随 plan 确认后方可执行**：编排脚本是 plan 任务拆解的执行器，随 plan 草稿一并全文过目。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。确认门一律用 human 形态行表达，不得派子智能体代行。
+- 收敛复核：派单返回后核对 diff 与授权文件范围（与 build.md 委派约定同口径）；BLOCKER 停住待处置。
+- **run journal 三条**：① 每个 stage 每次尝试出结果即 `wf-journal.mjs add` 记一行（含重试与 human 门结论）；② 中止后重跑先 `status`——已 pass 不重跑，从就绪层续；③ 收尾可把本 run 的 status 汇总粘 `workflow/delegations.md` 留痕（聚合脚本不读 journal）。
+- **journal 是自报态，非验证态**：run journal 由执行者（宿主 AI）自己记——concurrency / retry / 断点续跑语义的保证取决于记账纪律，编排层无运行时派发器强制（wf-run 已废，执行按本机制文档语义）；中止续跑时对「已 pass」结论保留人工核对权（2026-09-27 audit-gate-hardening 边界声明）。
+- 留痕：每个派单 / step stage 完成后向 `workflow/delegations.md` 委派结果表追加一行（`一次通过` / `返工×N` / `返工待修`，口径与 agg-delegations.cjs 对齐）。
+- 解析校验先行（机器门）：`node .agents/scripts/workflows-check.mjs`——role ∈ `.agents/roles/`、step ∈ `steps/`、after 引用存在且无环、四形态恰填一项、retries/concurrency 数值合法；任一不过即拒，不执行。

package/templates/_agents/workflows/pipeline-closing.md

@@ -0,0 +1,29 @@
+---
+name: pipeline-closing
+description: 推广环节 6 阶段闭环——起草 intent + plan（双写）→ 用户对话内确认 → 按 plan 改动面实施 → 3 关静态门（source-sync-check / npm test / doctor）→ 关单留痕（intent + plan → done + docs commit）。可复用于本项目所有 L1 推广环节（新增工具 / 微改动 / 协议修补）
+concurrency: 2
+---
+# workflow — pipeline-closing（推广环节 6 阶段闭环）
+
+> 把 5 个已闭环推广环节（E/A/D/C/F/B）的标准节奏固化为可复用编排。stage 用 role 派单 / gate 终端 / human 确认门三种形态——不引新 step（`_TEMPLATE.md` 解析校验要求 `step ∈ steps/`，新增 step 留给后续项目注册）。
+
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| author | — | implementer | — | 起草 intent + plan（双写 fill-{intent,plan}.mjs 生成草稿 + AI 填实），状态 draft | workflow/intents/<date>-<topic>.md, workflow/plans/<date>-<topic>.md | intent frontmatter 5 字段齐 + 状态 draft + 验收标准 ≥ 5 条；plan L1 极简 2 节齐 | | | 1 |
+| gate-doc | author | — | — | — | — | — | node .agents/scripts/fill-intent.test.mjs && node .agents/scripts/fill-plan.test.mjs | | |
+| confirm | gate-doc | — | — | plan 草稿全文过目，用户对话内一句"可以" → plan 状态 draft → approved + 回填「确认与复核」节 | — | plan 状态 approved + 「确认结果：approved（YYYY-MM-DD 用户对话内确认）」 | | 用户确认（plan 确认门） | |
+| plan-commit | confirm | implementer | — | 提交 plan 立项 commit（docs(workflow)） | workflow/intents/, workflow/plans/, workflow/INDEX.md | pre-commit 钩子全过；commit message 含 plan 改动面摘要 | | | 0 |
+| build | plan-commit | implementer | — | 按 plan §改动面 执行（含双源纪律：包源改了装副本手动同步） | 见 plan | plan 改动面全部完成；双源文件 sha 一致 | | | 1 |
+| gate-sync | build | — | — | — | — | — | node .agents/scripts/source-sync-check.mjs --diff（必须 0 差异） | | |
+| gate-test | build | — | — | — | — | — | npm test（必须全绿） | | |
+| gate-doctor | build | — | — | — | — | — | node bin/flow-kit.mjs doctor（必须 0 FAIL） | | |
+| feat-commit | gate-sync,gate-test,gate-doctor | implementer | — | 提交 feat commit（feat(模块名)） | 工作区所有变更文件 | pre-commit 钩子全过；commit message 含 build 改动面摘要 | | | 0 |
+| closeout | feat-commit | implementer | — | 补 intent 8 条验收勾验 + plan → done + 关单 docs commit 留痕；同步 INDEX.md（如适用） | workflow/intents/<date>-<topic>.md, workflow/plans/<date>-<topic>.md, workflow/INDEX.md | intent + plan 状态均 done；8 条验收勾验含 commit SHA 证据；commit message 含关单 commit + 8 条勾验摘要 | | | 0 |
+
+**编排语义**：第 0 层 author → 第 1 层 gate-doc + confirm（confirm 为 human 确认门形态——宿主 AI 停下询问用户，不派子智能体；通过才派下层）→ 第 2 层 plan-commit → 第 3 层 build → 第 4 层 3 关静态门（并行 fan-out）→ 第 5 层 feat-commit → 第 6 层 closeout。失败且 retries > 0 → 重派（全新上下文）；gate 非零 / human 驳回 → 中止后续、汇总报告失败项。每个 stage 每次尝试出结果记 `wf-journal.mjs add`；中止续跑先 `wf-journal.mjs status --wf pipeline-closing`（已 pass 不重跑）。
+
+**纪律**（先读）：
+- 声明随 plan 确认后方可执行——本 workflow 是 plan 任务拆解的执行器；plan 草稿先经用户对话内确认。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。确认门一律 human 形态行表达（confirm 行即此），不得派子智能体代行。
+- 留痕：每个派单 stage 完成后向 `workflow/delegations.md` 委派结果表追加一行（`一次通过` / `返工×N` / `返工待修`）。
+- 解析校验先行（机器门 `node .agents/scripts/workflows-check.mjs`）：role ∈ `.agents/roles/`、after 引用存在且无环、四形态恰填一项——任一不过即拒，不执行。