agentic-flow-kit 0.2.0 → 0.2.1

package/templates/_agents/scripts/commit-check-trigger.test.mjs

@@ -0,0 +1,94 @@
+// commit-check-trigger.test.mjs — builds/checks 触发判定测试（ext 全局 / prefix 前缀 / 双不命中 / 引擎自改豁免 / --full）。
+// 方法：临时 git 仓库 + 被测 hook + 假构建命令（node -e 打标）——不跑真实构建，秒级完成。
+// 命名避开装户项目的 commit-check.test.mjs（敏感判据测试，项目自持）——本文件测触发器，随包走。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HOOK = path.join(SCRIPT_DIR, '..', 'hooks', 'commit-check.cjs');
+const MARK = 'TRIGGER_TEST_BUILD_RAN';
+
+let pass = 0, fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n       ${detail}` : ''}`); }
+};
+const git = (root, args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+
+// mkfix：临时 git 仓 + hook + 触发器假配置（构建命令 = 打标文件，跑没跑看标记存在性）
+const mkfix = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-trigger-test-'));
+  git(root, ['init', '-q']);
+  git(root, ['config', 'user.email', 't@t']);
+  git(root, ['config', 'user.name', 't']);
+  fs.mkdirSync(path.join(root, '.agents', 'hooks'), { recursive: true });
+  fs.copyFileSync(HOOK, path.join(root, '.agents', 'hooks', 'commit-check.cjs'));
+  const marks = path.join(root, 'marks');
+  const cmd = (name) => `node -e "require('fs').writeFileSync('${marks.replaceAll('\\', '/').replaceAll('\'', '\\\'')}/${name}','')"`;
+  fs.mkdirSync(marks);
+  fs.writeFileSync(path.join(root, '.agents', 'hooks', 'commit-check.config.json'), JSON.stringify({
+    knownPatterns: [],
+    builds: [
+      { name: 'extbuild', command: cmd('extbuild'), ext: ['.xyz'] },
+      { name: 'prefixbuild', command: cmd('prefixbuild'), prefix: 'docs/' },
+    ],
+    checks: [],
+  }));
+  return { root, marks };
+};
+
+// stage：写文件并暂存，跑 hook（extraArgs 透传如 --full），返回 { status, out, ran }
+const runHook = (root, extraArgs = []) => {
+  const r = spawnSync('node', ['.agents/hooks/commit-check.cjs', ...extraArgs], { cwd: root, encoding: 'utf8' });
+  return { status: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+const stage = (root, rel, content) => {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf8');
+  git(root, ['add', '--', rel]);
+};
+const ran = (marks, name) => fs.existsSync(path.join(marks, name));
+
+let f = mkfix();
+
+// 场景 1：ext 全局触发——任意目录下 .xyz 命中 extbuild
+stage(f.root, 'src/a.xyz', 'x');
+let r = runHook(f.root);
+check('S1 ext 全局触发（.xyz → extbuild 跑）', ran(f.marks, 'extbuild') && r.status === 0, r.out);
+
+// 场景 2：prefix 前缀触发——docs/ 下任意文件命中 prefixbuild；其他位置同名扩展不命中
+f = mkfix();
+stage(f.root, 'wiki/看板.html', '<html></html>');
+r = runHook(f.root);
+check('S2 prefix 外的 .html 不触发 prefixbuild（wiki html 场景）', !ran(f.marks, 'prefixbuild') && r.status === 0, r.out);
+stage(f.root, 'docs/readme.md', 'doc');
+r = runHook(f.root);
+check('S2b docs/ 前缀任意文件触发 prefixbuild', ran(f.marks, 'prefixbuild') && r.status === 0, r.out);
+
+// 场景 3：双不命中 → SKIP 提示且零构建
+f = mkfix();
+stage(f.root, 'notes/other.txt', 'plain');
+r = runHook(f.root);
+check('S3 双不命中 → SKIP 提示、无构建', r.out.includes('SKIP') && !ran(f.marks, 'extbuild') && !ran(f.marks, 'prefixbuild') && r.status === 0, r.out);
+
+// 场景 4：引擎自改豁免——.agents/ 下即使放 .xyz 也不触发构建
+f = mkfix();
+stage(f.root, '.agents/scripts/engine.xyz', 'engine');
+r = runHook(f.root);
+check('S4 .agents/ 自身变更不触发构建', !ran(f.marks, 'extbuild') && r.status === 0, r.out);
+
+// 场景 5：--full 全跑（合并提交口径）
+f = mkfix();
+stage(f.root, 'unrelated.txt', 'x');
+r = runHook(f.root, ['--full']);
+check('S5 --full 无条件全跑全部 builds', ran(f.marks, 'extbuild') && ran(f.marks, 'prefixbuild') && r.status === 0, r.out);
+
+for (const d of fs.readdirSync(os.tmpdir()).filter((x) => x.startsWith('cc-trigger-test-'))) {
+  fs.rmSync(path.join(os.tmpdir(), d), { recursive: true, force: true });
+}
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/ensure-board.ps1

@@ -1,4 +1,4 @@
-# ensure-board.ps1 — 任务入口幂等拉起 workflow 看板（只起不关：Windows 重启即天然回收，无需 stop/status）
+# ensure-board.ps1 — workflow 看板按需手动拉起（默认不自动开启；只起不关：Windows 重启即天然回收，无需 stop/status）
 # 行为：探活（端口占用者须响应 /api/board 才认定为看板，否则不动手、报占用者并 exit 1）
 #       → 前端或服务端任一代码早于进程 = 旧代码自动 kill 重启 → 全新启动成功后弹浏览器（重启/已运行不弹，SSE 自动重连）
 # 用法：powershell -NoProfile -File .agents/scripts/ensure-board.ps1 [-Port 8933] [-NoOpen]

package/templates/_agents/scripts/gen-wiki-board.mjs

@@ -92,7 +92,8 @@ const archiveCount = (() => {
       else if (!gitIgnoredArchive.has(r)) n++;
     }
   };
-  walk(path.join(WIKI, 'drafts-archive'));
+  if (fs.existsSync(path.join(WIKI, 'drafts-archive'))) walk(path.join(WIKI, 'drafts-archive'));
+  else console.error('⚠️ wiki/drafts-archive/ 不存在，归档计数按 0 处理（wiki 协议目录，建议恢复）');
   return n;
 })();
 
@@ -135,8 +136,13 @@ let out = indexText;
   const fixedRows = [...overviewRows, '| drafts-archive | — | 原文档备份（按 日期-主题 分目录） |'];
   out = [...lines.slice(0, headIdx), '| 主题 | 文件数 | 用途 |', '|---|---|---|', ...fixedRows, ...lines.slice(lastData + 1)].join(eol);
 }
-// 合计行数字
-out = out.replace(/合计：\*\*\d+ 份\*\*知识文档，\*\*\d+ 个主题\*\*/, `合计：**${totalFiles} 份**知识文档，**${diskTopics.size} 个主题**`);
+// 合计行数字（锚点缺失即 fail-loud——静默 no-op 会让合计行悄悄陈旧，2026-09-24 审查修复）
+const totalRe = /合计：\*\*\d+ 份\*\*知识文档，\*\*\d+ 个主题\*\*/;
+if (!totalRe.test(out)) {
+  console.error('❌ INDEX「合计」行锚点未找到（须形如「合计：**N 份**知识文档，**M 个主题**」），未写盘');
+  process.exit(1);
+}
+out = out.replace(totalRe, `合计：**${totalFiles} 份**知识文档，**${diskTopics.size} 个主题**`);
 // 映射表区（节标题之间整段重写）
 {
   const lines = out.split(/\r?\n/);
@@ -144,6 +150,10 @@ out = out.replace(/合计：\*\*\d+ 份\*\*知识文档，\*\*\d+ 个主题\*\*/
   const e = lines.findIndex((l) => l.startsWith('## 命名规则'));
   if (s >= 0 && e > s) {
     out = [...lines.slice(0, s + 1), '', mappingSection, '', '---', '', ...lines.slice(e)].join(eol);
+  } else {
+    // 锚点缺失即 fail-loud（对齐速览表/合计行口径）——曾静默跳过致映射表悄悄陈旧仍报 ✅（2026-09-24 审查修复）
+    console.error('❌ INDEX 映射表锚点未找到（须有「## 文件 → 主题 → 归属目录 映射表」与其后的「## 命名规则」），未写盘');
+    process.exit(1);
   }
 }
 

package/templates/_agents/scripts/gen-wiki-board.test.mjs

@@ -128,6 +128,28 @@ const runGen = (root) => spawnSync(process.execPath, [GEN], { cwd: root, encodin
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 4：映射表锚点缺失 → fail-loud（2026-09-24 审查修复：原静默跳过致映射表悄悄陈旧仍报成功）----
+{
+  const root = mkfix('\n');
+  const idx = path.join(root, 'wiki', 'INDEX.md');
+  fs.writeFileSync(idx, fs.readFileSync(idx, 'utf8').replace(/^## 文件 → 主题 → 归属目录 映射表$/m, '## 映射（锚点被改）'), 'utf8');
+  const r = runGen(root);
+  check('场景 4：映射表锚点缺失 → exit 1', r.status === 1, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 4：报错点名映射表锚点', (r.stderr || '').includes('映射表锚点'), r.stderr);
+  check('场景 4：未写盘（INDEX 原样保留）', fs.readFileSync(idx, 'utf8').includes('## 映射（锚点被改）'), '');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 5：drafts-archive 缺失 → 不崩栈，警告 + 归档按 0（2026-09-24 审查修复）----
+{
+  const root = mkfix('\n');
+  fs.rmSync(path.join(root, 'wiki', 'drafts-archive'), { recursive: true });
+  const r = runGen(root);
+  check('场景 5：drafts-archive 缺失 → exit 0（不崩栈）', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 5：stderr 有缺失警告', (r.stderr || '').includes('drafts-archive'), r.stderr);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

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

@@ -55,7 +55,8 @@ function parseDoc(text) {
   }
   const h1 = text.match(/^# (.+)$/m);
   let title = h1 ? h1[1] : '';
-  const dash = title.match(/\S+\s*[—–-]+\s*(.+)$/);
+  // 前缀分隔只认 em/en dash（任意间距）或带空格的 ASCII 连字符——裸连字符是 kebab-case 的一部分，不截断（2026-09-24）
+  const dash = title.match(/\S+\s*(?:[—–]+|\s-\s)\s*(.+)$/);
   if (dash) title = dash[1];
   return { meta, title };
 }
@@ -142,8 +143,12 @@ const docs = scan();
 const existing = fs.existsSync(INDEX_P) ? fs.readFileSync(INDEX_P, 'utf8') : '';
 const inner = `${BEGIN}\n\n${render(docs)}\n\n${END}`;
 let out;
-if (existing.includes(BEGIN) && existing.includes(END)) {
+if (existing.includes(BEGIN) && existing.includes(END) && existing.indexOf(BEGIN) < existing.indexOf(END)) {
   out = existing.slice(0, existing.indexOf(BEGIN)) + inner + existing.slice(existing.indexOf(END) + END.length);
+} else if (existing.includes(BEGIN) || existing.includes(END)) {
+  // 锚点残缺（END 被手工截断 / 顺序颠倒）：fail-loud 不写盘——曾走 append 分支产生双 GENERATED 区，旧区永不清理（2026-09-24）
+  console.error('❌ workflow/INDEX.md 生成锚点不完整（GENERATED:BEGIN/END 须成对且 BEGIN 在前）——手工修复锚点后重跑，未写盘');
+  process.exit(1);
 } else {
   out = (existing ? existing.replace(/\s*$/, '') + '\n\n' : HEADER) + inner + '\n';
 }

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

@@ -105,6 +105,33 @@ const run = (root, args = []) => spawnSync(process.execPath, [GEN, ...args], { c
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 5：kebab-case H1 不被连字符截断（2026-09-24 前缀正则收窄回归）----
+{
+  const root = mkfix();
+  fs.writeFileSync(path.join(root, 'workflow', 'intents', '2026-09-22-kebab.md'), doc(
+    '状态: draft\n级别: L1\n日期: 2026-09-22\n模块: pipeline',
+    'workflow-doc-retrieval',
+  ), 'utf8');
+  const r = run(root);
+  const idx = fs.readFileSync(path.join(root, 'workflow', 'INDEX.md'), 'utf8');
+  check('场景 5：kebab-case H1 完整保留（未被截成末段）', idx.includes('| workflow-doc-retrieval |') && !idx.includes('| retrieval |'), idx.split('\n').filter((l) => l.includes('retrieval')).join('\n'));
+  check('场景 5：em-dash 前缀仍正常剥离', idx.includes('| 在跑的需求甲 |'), '');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 6：END 锚点被截断 → fail-loud 不写盘（2026-09-24：原 append 分支产生双生成区）----
+{
+  const root = mkfix();
+  run(root);
+  const p = path.join(root, 'workflow', 'INDEX.md');
+  fs.writeFileSync(p, fs.readFileSync(p, 'utf8').replace('<!-- GENERATED:END -->', ''), 'utf8');
+  const r = run(root);
+  check('场景 6：END 锚点缺失 → exit 1', r.status === 1, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 6：报错点名锚点不完整', (r.stderr || '').includes('锚点不完整'), r.stderr);
+  check('场景 6：未写盘（无双重生成区）', (fs.readFileSync(p, 'utf8').match(/GENERATED:BEGIN/g) || []).length === 1, '');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

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

@@ -99,20 +99,34 @@ function scanSurface() {
     let label = pat;
     if (pat.endsWith('/')) {
       const dir = pat.slice(0, -1);
+      if (!fs.existsSync(dir)) { console.error(`⚠️ 预算目录不存在，跳过该条：${pat}`); continue; }
       for (const f of fs.readdirSync(dir)) sum += fs.statSync(path.join(dir, f)).size;
       max = sum;
       label = `${pat}（合计）`;
     } else if (pat.includes('*')) {
-      const dir = path.dirname(pat);
-      const suffix = pat.slice(pat.indexOf('*') + 1);
+      // 词表约定 glob = 基名内单个 `*`（<前缀>*<后缀>），目录段不支持通配——与 rule-budget.sh 的 shell glob 同口径。
+      // 多 `*` / 目录段含 `*` 出词表：警告跳过，不做「只按后缀 endsWith」的放宽式匹配（2026-09-24 收口：
+      // 曾按首个 * 取后缀，`pl*.md` 会误吃目录内全部 .md、`a*b` 会误吃一切 b 结尾文件）
+      const stars = pat.split('*').length - 1;
+      const starIdx = pat.indexOf('*');
+      const lastSlash = pat.lastIndexOf('/');
+      if (stars !== 1 || starIdx < lastSlash) {
+        console.error(`⚠️ 预算表 glob 仅支持基名内单个 *（<前缀>*<后缀>），跳过该条：${pat}`);
+        continue;
+      }
+      const dir = lastSlash >= 0 ? pat.slice(0, lastSlash + 1) : '.';
+      const basePrefix = pat.slice(lastSlash + 1, starIdx);
+      const baseSuffix = pat.slice(starIdx + 1);
+      if (!fs.existsSync(dir)) { console.error(`⚠️ 预算目录不存在，跳过该条：${pat}`); continue; }
       for (const f of fs.readdirSync(dir)) {
-        if (!f.endsWith(suffix)) continue;
+        if (!f.startsWith(basePrefix) || !f.endsWith(baseSuffix)) continue;
         const s = fs.statSync(path.join(dir, f)).size;
         sum += s;
         if (s > max) max = s;
       }
       label = `${pat}（单篇最大）`;
     } else {
+      if (!fs.existsSync(pat)) { console.error(`⚠️ 预算文件不存在，跳过该条：${pat}`); continue; }
       sum = max = fs.statSync(pat).size;
     }
     entries.push({ pat, label, sum, max, lim, pct: (max / lim) * 100, isDir: pat.endsWith('/') });

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

@@ -93,6 +93,27 @@ const readMetrics = (root) => fs.readFileSync(path.join(root, 'workflow', 'metri
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 4：预算表 glob 词表收口——单 * 前缀+后缀匹配；多 * / 目录段 * 警告跳过（2026-09-24）----
+{
+  const root = mkfix();
+  fs.writeFileSync(path.join(root, '.agents', 'commands', 'zeta.md'), 'z'.repeat(500), 'utf8'); // 非 pl 前缀：不得被 pl*.md 吃进
+  fs.writeFileSync(path.join(root, '.agents', 'rule-budgets.txt'), [
+    '# fixture 预算表（glob 词表收口）',
+    'AGENTS.md 100',
+    '.agents/commands/pl*.md 9999',
+    '.agents/commands/**.md 9999',
+    '.agents/*/cmd.md 9999',
+    '',
+  ].join('\n'), 'utf8');
+  const r = run(root, ['--month', '2026-09']);
+  const md = fs.existsSync(path.join(root, 'workflow', 'metrics.md')) ? readMetrics(root) : '';
+  check('场景 4：exit 0（词表外条目跳过不阻断）', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 4：单 * 按前缀+后缀匹配（pl*.md 只吃 plan.md 10B，zeta.md 500B 不计入）', /\.agents\/commands\/pl\*\.md（单篇最大）\s+10\s+\/\s+9999/.test(r.stdout), r.stdout);
+  check('场景 4：常驻面合计随之正确（120+10=130B → 0.1 KB）', /0\.1 KB（峰值/.test(md) && /常驻面合计：0\.1 KB/.test(r.stdout), `${md}\n${r.stdout}`);
+  check('场景 4：多 * 与目录段 * 各警告跳过', (r.stderr || '').includes('**.md') && (r.stderr || '').includes('.agents/*/cmd.md'), r.stderr);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

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

@@ -95,7 +95,8 @@ function parseDoc(text) {
   }
   const h1 = text.match(/^# (.+)$/m);
   let title = h1 ? h1[1] : '';
-  const dash = title.match(/\S+\s*[—–-]+\s*(.+)$/);
+  // 前缀分隔只认 em/en dash（任意间距）或带空格的 ASCII 连字符——裸连字符是 kebab-case 的一部分，不截断（2026-09-24）
+  const dash = title.match(/\S+\s*(?:[—–]+|\s-\s)\s*(.+)$/);
   if (dash) title = dash[1];
   return { meta, title };
 }

package/templates/_agents/scripts/rule-budget.sh

@@ -34,9 +34,15 @@ while IFS= read -r line; do
   case "$pat" in ''|'#'*) continue ;; esac
   case "$lim" in ''|*[!0-9]*) continue ;; esac
   case "$pat" in
-    */) # 目录合计：--staged 下仅当暂存触及该目录内文件才查
+    */) # 目录合计：--staged 下仅当暂存触及该目录内文件才查（case 字面前缀匹配——pat 含 . 时不能当正则用，2026-09-24）
       if [ "$MODE" = "--staged" ]; then
-        printf '%s\n' "$staged_list" | grep -q "^${pat}" || continue
+        found=0
+        while IFS= read -r sf; do
+          case "$sf" in "$pat"*) found=1 ;; esac
+        done <<EOF
+$staged_list
+EOF
+        [ "$found" = "1" ] || continue
       fi
       total=0
       for f in "$pat"*; do

package/templates/_agents/scripts/verify-wiki-consistency.mjs

@@ -73,7 +73,11 @@ const gitIgnoredArchive = (() => {
     return new Set();
   }
 })();
-const archiveCount = walkTree(path.join(WIKI, 'drafts-archive')).files.filter((r) => !gitIgnoredArchive.has(r)).length;
+// drafts-archive 缺失：ENOENT 崩栈改明示失败（本脚本是门禁，协议目录被删应 exit 1 而非崩栈，2026-09-24）
+const ARCHIVE_DIR = path.join(WIKI, 'drafts-archive');
+let archiveCount = 0;
+if (fs.existsSync(ARCHIVE_DIR)) archiveCount = walkTree(ARCHIVE_DIR).files.filter((r) => !gitIgnoredArchive.has(r)).length;
+else problems.push('wiki/drafts-archive/ 目录缺失（wiki 协议结构，模板自带）——归档一致性无从校验');
 
 // ---- 看板 DATA 解析 ----
 const html = fs.readFileSync(path.join(WIKI, '知识沉淀总览.html'), 'utf8');
@@ -175,6 +179,7 @@ for (const t of DATA.topics) {
     if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) deadLinks.push(`${t.name}/${f.file} → ${f.dir}`);
   }
 }
+// 静态 href 扫描守的是「手工编辑看板」时加的链接（生成链接全在 JS 运行时拼，不落静态属性）——看板是 owned 内容，人为改动须可达
 for (const m2 of html.matchAll(/href="([^"]+)"/g)) {
   const href = m2[1];
   if (/^(https?:|mailto:|#)/i.test(href) || href.includes('${')) continue; // 外链 / 锚点 / 模板占位