agentic-flow-kit 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow-kit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {

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

@@ -117,7 +117,8 @@ import { laneOfEntry } from './stage-gates.mjs';
 import { MARK_RE, approvedTraceHit } from './stage-gates.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const GIT = process.platform === 'win32' ? 'git.exe' : 'git';
+// CHECK_LOOP_GIT：测试注入钩子（指向不存在/不可执行路径可稳定触发 spawn 异常）；未设置时与原行为逐字节一致（2026-10-05-gitout-fail-open）
+const GIT = process.env.CHECK_LOOP_GIT || (process.platform === 'win32' ? 'git.exe' : 'git');
 
 function takeOpts() {
   const args = process.argv.slice(2);
@@ -210,19 +211,52 @@ const inSet = (v, arr) => arr.includes(v);
 const stOkDoc = (st) => inSet(st, ENUMS['doc.status.confirmed']);
 
 // git 调用（参数数组形式不走 shell——Windows cmd 不认单引号；git.exe 显式解析沿 doctor 先例）
+// 基础设施异常与业务失败分流（2026-10-05-gitout-fail-open）：spawn 异常响亮出账（进程级去重恰一条，
+// 沿检查 16 装户「载入失败响亮出账」先例）+ 瞬时类错误码单次重试；「非 git 仓」（status≠0）仍是
+// 合法装户语义、静默走降级。intentional-simple: 重试后仍异常继续走原降级/拦截语义（连续瞬时异常
+// 残余面小且有账可查）；升级路径 = 探测门（:720/:796）改三态拆分
+let gitInfraWarned = false;
+function warnGitInfra(args, code) {
+  if (gitInfraWarned) return;
+  gitInfraWarned = true;
+  console.error(`check-loop: git 探测异常 ${args[0]}（${code}）——按非 git 仓降级，检查面可能收窄`);
+}
+const GIT_TRANSIENT = new Set(['EAGAIN', 'EPERM', 'EMFILE', 'EINTR']);
+function spawnGit(args) {
+  const opts = { cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 };
+  let r = spawnSync(GIT, args, opts);
+  if (r.error) {
+    // 出账在重试终败后（与 linesOf 对称——瞬时重试恢复成功不打扰）；非瞬时类直接出账
+    if (GIT_TRANSIENT.has(r.error.code)) r = spawnSync(GIT, args, opts);
+    if (r.error) warnGitInfra(args, r.error.code || r.error.message);
+  }
+  return r;
+}
 function gitOut(args, { ok = () => true } = {}) {
-  const r = spawnSync(GIT, args,
-    { cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  const r = spawnGit(args);
   if (r.error || r.status !== 0 || !ok(r)) return null;
   return r.stdout || '';
 }
 
 // ---- frontmatter 受限子集读取（fm_get 语义：首行 --- 进入、下一 --- 闭合、键在行首、首个命中、值两侧去空白）----
+// fs 读取同走 fail-loud（2026-10-05-gitout-fail-open 实现期诊断追加，与 spawnGit 同一故障类）：
+// readFileSync 瞬时异常（宿主资源压力 EMFILE/共享冲突类）重试一次，仍失败响亮出账（进程级去重）
+// 后按 null 降级——调用方按空文档跳过该件，但异常本身不再静默
+let fsReadWarned = false;
 const fileLinesCache = new Map();
 function linesOf(file) {
   if (!fileLinesCache.has(file)) {
-    try { fileLinesCache.set(file, fs.readFileSync(file, 'utf8').split(/\r?\n/)); }
-    catch { fileLinesCache.set(file, null); }
+    let lines = null;
+    try {
+      lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+    } catch (e) {
+      try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/); } catch { lines = null; }
+      if (!lines && !fsReadWarned) {
+        fsReadWarned = true;
+        console.error(`check-loop: 文档读取异常 ${path.basename(file)}（${e.code || e.message}）——按空文档降级，检查面可能收窄`);
+      }
+    }
+    fileLinesCache.set(file, lines);
   }
   return fileLinesCache.get(file);
 }
@@ -578,7 +612,9 @@ function verifyEvidenceTruth(evidenceStr, planBase, root) {
   if (!shaMatch || /^\d+$/.test(shaMatch[1])) return { ok: true, type: 'text' };
 
   const sha = shaMatch[1];
-  const revParse = spawnSync(GIT, ['rev-parse', sha], { cwd: ROOT, encoding: 'utf8' });
+  // 直连走 spawnGit（与 gitOut 同一 loud+retry 通道，注释互引）：spawn 异常不再被静默算作业务失败；
+  // 重试后仍异常按下方 status!==0 判定（fail-closed 保持——本地核验不了就按伪造拦）
+  const revParse = spawnGit(['rev-parse', sha]);
   if (revParse.status !== 0) {
     // 区分本地伪造与外部仓库引用：
     // 剔除 SHA 与泛指词后仍有其他内容（如项目名、路径描述）→ 视为外部仓库引用，不硬拦（本地无法核验他仓哈希）；
@@ -607,7 +643,7 @@ function verifyEvidenceTruth(evidenceStr, planBase, root) {
     }
   }
 
-  const show = spawnSync(GIT, ['show', '--name-only', sha], { cwd: ROOT, encoding: 'utf8' });
+  const show = spawnGit(['show', '--name-only', sha]);
   if (show.status !== 0) return { ok: false, type: 'error', msg: `无法读取提交 ${sha} 的文件列表` };
   
   const changedFiles = show.stdout.split(/\r?\n/).filter(Boolean);
@@ -617,7 +653,7 @@ function verifyEvidenceTruth(evidenceStr, planBase, root) {
     // 过程证据（2026-10-03 check-evidence-process）：执行器驱动的提交可作验收证据——提交信息带
     // 「pipeline-run <runId>」标记（docsCommit 四种格式共有段，runId 严格形态 日期8-时间4-主题-尾；
     // 与 run 事件流同源，git 历史留痕可对质）。只救 irrelevant：forged（SHA 不存在）在前已判，其余判据不动。
-    const subj = spawnSync(GIT, ['log', '-1', '--format=%s', sha], { cwd: ROOT, encoding: 'utf8' });
+    const subj = spawnGit(['log', '-1', '--format=%s', sha]);
     if (subj.status === 0 && /pipeline-run [0-9]{8}-[0-9]{4}-[A-Za-z0-9-]+/.test(subj.stdout)) {
       return { ok: true, type: 'process' };
     }

package/templates/_agents/scripts/check-loop.test.mjs

@@ -68,9 +68,12 @@ ${refs ? '     - 是 → ../intents/2026-09-12-ghost.md\n' : ' - 否 → 理由:
 `;
 
 // run：默认 CHECK_LOOP_ROOT 注入（fixture 模式）；{git:true} 时 cwd 注入（真 git 模式，测 tracked 过滤）；
-// opts.args 追加 CLI 参数（--hardening 等加固门场景用，2026-09-30 hybrid-governance-explore-hardening）
+// opts.args 追加 CLI 参数（--hardening 等加固门场景用，2026-09-30 hybrid-governance-explore-hardening）；
+// opts.env 增量覆盖子进程 env（CHECK_LOOP_GIT 替身注入用，2026-10-05-gitout-fail-open）
 const run = (root, opts = {}) => spawnSync(process.execPath, [CHECK_LOOP, ...(opts.args || [])], {
-  ...(opts.git ? { cwd: root } : { cwd: ROOT_CWD, env: { ...process.env, CHECK_LOOP_ROOT: root } }),
+  ...(opts.git
+    ? { cwd: root, ...(opts.env ? { env: { ...process.env, ...opts.env } } : {}) }
+    : { cwd: ROOT_CWD, env: { ...process.env, ...(opts.env || {}), CHECK_LOOP_ROOT: root } }),
   encoding: 'utf8',
 });
 const ROOT_CWD = process.cwd();
@@ -83,13 +86,32 @@ const expectOk = (desc, root) => {
   const r = run(root);
   check(desc, r.status === 0, `exit=${r.status}\n${outOf(r)}`);
 };
+// 夹具 git 调用防瞬时失败（2026-10-05-gitout-fail-open 夹具侧加固）：宿主/CI 资源压力下 spawnSync 可能
+// 瞬时 `r.error`，git 侧也可能瞬时 status≠0（如 index.lock 争用）——对夹具 setup 调用（init/add/commit/
+// rev-parse）两者都永不合法：重试一次，持续失败抛错响亮失败。绝不静默产出空 sha / 缺提交的假夹具
+// （那会让证据场景拿到「无裁决」的错误结果——CI run 37252874044 flake 的实际根因侧，诊断详见同名 incident）
+function gitRetry(args, root) {
+  const opts = { cwd: root, encoding: 'utf8' };
+  let r = spawnSync(GIT, args, opts);
+  if (r.error || r.status !== 0) {
+    r = spawnSync(GIT, args, opts);
+    if (r.error || r.status !== 0) {
+      throw new Error(`fixture git 瞬时失败（重试后仍 ${r.error ? (r.error.code || r.error.message) : `exit ${r.status}`}）: git ${args.join(' ')}\n${(r.stderr || '').slice(0, 300)}`);
+    }
+  }
+  return r;
+}
+const shortSha = (root, args = ['rev-parse', '--short', 'HEAD']) => {
+  const out = gitRetry(args, root).stdout.trim();
+  if (!out) throw new Error(`fixture git 空输出（假夹具防线）: git ${args.join(' ')}`);
+  return out;
+};
 const gitInit = (root) => {
-  spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', ['init', '-q'], { cwd: root });
+  gitRetry(['init', '-q'], root);
 };
 const gitCommitAll = (root, msg) => {
-  const G = process.platform === 'win32' ? 'git.exe' : 'git';
-  spawnSync(G, ['add', '-A'], { cwd: root });
-  spawnSync(G, ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', msg], { cwd: root });
+  gitRetry(['add', '-A'], root);
+  gitRetry(['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', msg], root);
 };
 const rmfix = (root) => fs.rmSync(root, { recursive: true, force: true });
 // writeLedger：fixture 台账辅助（检查 15 配对用；行 schema 同 confirm-doc.mjs appendLedger）
@@ -435,12 +457,12 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
     fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'rule-budgets.txt'), path.join(T, '.agents', 'rule-budgets.txt'));
     gitInit(T);
     w(T, 'AGENTS.md', 'x'.repeat(8000));
-    spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', ['add', 'AGENTS.md'], { cwd: T });
+    gitRetry(['add', 'AGENTS.md'], T);
     let r = spawnSync('sh', ['.agents/scripts/rule-budget.sh', '--staged'], { cwd: T, encoding: 'utf8' });
     check('rule-budget --staged:暂存超限 → exit 1（硬拦路径）',
       r.status === 1 && `${r.stdout}${r.stderr}`.includes('常驻面超限：AGENTS.md'), `${r.stdout}${r.stderr}`);
     w(T, 'AGENTS.md', '# 小体积\n');
-    spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', ['add', 'AGENTS.md'], { cwd: T });
+    gitRetry(['add', 'AGENTS.md'], T);
     r = spawnSync('sh', ['.agents/scripts/rule-budget.sh', '--staged'], { cwd: T, encoding: 'utf8' });
     check('rule-budget --staged:合规 → exit 0（不误拦）', r.status === 0, `${r.stdout}${r.stderr}`);
     rmfix(T);
@@ -582,7 +604,7 @@ const evidenceFixture = (slug, declared, createDeclared) => {
   w(T, `workflow/intents/2026-10-04-${slug}.md`, INTENT(slug, '状态: done\n级别: L1\n日期: 2026-10-04',
     '\n## 验收标准（可测试）\n- [x] 用例通过（证据:commit PLACEHOLDER）\n'));
   gitCommitAll(T, `feat: ${slug} fixture`);
-  const sha = spawnSync(GIT, ['rev-parse', 'HEAD'], { cwd: T, encoding: 'utf8' }).stdout.trim().slice(0, 7);
+  const sha = shortSha(T, ['rev-parse', 'HEAD']).slice(0, 7);
   w(T, `workflow/intents/2026-10-04-${slug}.md`, INTENT(slug, '状态: done\n级别: L1\n日期: 2026-10-04',
     `\n## 验收标准（可测试）\n- [x] 用例通过（证据:commit ${sha}）\n`));
   gitCommitAll(T, `docs: ${slug} evidence`);
@@ -620,7 +642,7 @@ const evidenceFixture = (slug, declared, createDeclared) => {
   fs.mkdirSync(path.join(T, 'src'), { recursive: true });
   w(T, 'src/app.mjs', '// fixture\n');
   gitCommitAll(T, 'feat: sh1 实现（无执行器标记）');
-  const sha = spawnSync(GIT, ['rev-parse', '--short', 'HEAD'], { cwd: T, encoding: 'utf8' }).stdout.trim();
+  const sha = shortSha(T);
   w(T, 'workflow/intents/2026-09-26-sh1.md', INTENT('sh1', '状态: done\n级别: L1\n日期: 2026-09-26', `\n## 验收标准（可测试）\n- [x] 用例通过（证据:${sha}）\n`));
   expectOk('证据 SHA 触及声明文件（无执行器标记）→ type=sha 校验通过 exit 0', T);
   rmfix(T);
@@ -672,8 +694,7 @@ const evidenceFixture = (slug, declared, createDeclared) => {
   fs.mkdirSync(path.join(T, 'notes'), { recursive: true });
   w(T, 'notes/other.md', 'x\n');
   gitCommitAll(T, 'docs(x): 演练穿越（pipeline-run 20260926-0900-pe1-abc1）');
-  const G = process.platform === 'win32' ? 'git.exe' : 'git';
-  const sha = spawnSync(G, ['rev-parse', '--short', 'HEAD'], { cwd: T, encoding: 'utf8' }).stdout.trim();
+  const sha = shortSha(T);
   w(T, 'workflow/intents/2026-09-26-pe1.md', INTENT('pe1', '状态: done\n级别: L1\n日期: 2026-09-26', `\n## 验收标准（可测试）\n- [x] 演练穿越（证据:${sha}）\n`));
   expectOk('过程证据:提交信息带执行器标记（改动面外）→ 放行 exit 0', T);
   rmfix(T);
@@ -685,8 +706,7 @@ const evidenceFixture = (slug, declared, createDeclared) => {
   fs.mkdirSync(path.join(T, 'notes'), { recursive: true });
   w(T, 'notes/other.md', 'x\n');
   gitCommitAll(T, 'docs(x): 演练穿越（L0，无标记提交）');
-  const G = process.platform === 'win32' ? 'git.exe' : 'git';
-  const sha = spawnSync(G, ['rev-parse', '--short', 'HEAD'], { cwd: T, encoding: 'utf8' }).stdout.trim();
+  const sha = shortSha(T);
   w(T, 'workflow/intents/2026-09-26-pe2.md', INTENT('pe2', '状态: done\n级别: L1\n日期: 2026-09-26', `\n## 验收标准（可测试）\n- [x] 演练穿越（证据:${sha}）\n`));
   expectHard('过程证据:无标记无关提交 → 仍拦 证据无关', T, '证据无关');
   rmfix(T);
@@ -699,6 +719,41 @@ const evidenceFixture = (slug, declared, createDeclared) => {
   expectHard('过程证据:SHA 不存在 → forged 仍拦（防伪线不放松）', T, '证据伪造');
   rmfix(T);
 }
+// ---- 场景 5v:git 基础设施异常 fail-loud（2026-10-05-gitout-fail-open）----
+// CHECK_LOOP_GIT 指向不存在路径 → spawnSync 跨平台稳定 r.error（ENOENT）→ 响亮出账恰一条（进程去重）
+// + 证据核验降级（exit 语义不变、无业务裁决误报）；正常 git 零出账（防误报负例）
+// 注（L2 复核 P2-2）：出账断言不构成 :581 接入 spawnGit 的独立钉死——探测门与 :581 共用去重 flag，
+// 变异（:581 改回裸 spawnSync）三断言仍绿；:581 接线由代码走读 + CI 覆盖，瞬时重试路径静态替身不可测
+{
+  const T = mkfix();
+  gitInit(T);
+  w(T, 'workflow/plans/2026-09-26-pe4.md', PLAN('pe4', '状态: done\n级别: L1\n模块: material', '\n## 改动方案\n\n- src/app.mjs：实现功能\n'));
+  fs.mkdirSync(path.join(T, 'notes'), { recursive: true });
+  w(T, 'notes/other.md', 'x\n');
+  gitCommitAll(T, 'docs(x): 演练穿越（L0，无标记提交）');
+  const sha = shortSha(T);
+  w(T, 'workflow/intents/2026-09-26-pe4.md', INTENT('pe4', '状态: done\n级别: L1\n日期: 2026-09-26', `\n## 验收标准（可测试）\n- [x] 演练穿越（证据:${sha}）\n`));
+  const r = run(T, { env: { CHECK_LOOP_GIT: 'definitely-not-git-xyz-2026' } });
+  const hits = outOf(r).split('git 探测异常').length - 1;
+  check('git 基础设施异常:响亮出账恰一条（进程去重）', hits === 1, `hits=${hits}\n${outOf(r)}`);
+  check('git 基础设施异常:持续异常仍 fail-closed（伪造拦不放松，防静默降级）', r.status === 1 && outOf(r).includes('证据伪造'), `exit=${r.status}\n${outOf(r)}`);
+  check('git 基础设施异常:基础设施异常不冒充业务裁决（无证据无关误报）', !outOf(r).includes('证据无关'), outOf(r));
+  rmfix(T);
+}
+{
+  const T = mkfix();
+  gitInit(T);
+  w(T, 'workflow/plans/2026-09-26-pe5.md', PLAN('pe5', '状态: done\n级别: L1\n模块: material', '\n## 改动方案\n\n- src/app.mjs：实现功能\n'));
+  fs.mkdirSync(path.join(T, 'notes'), { recursive: true });
+  w(T, 'notes/other.md', 'x\n');
+  gitCommitAll(T, 'docs(x): 演练穿越（L0，无标记提交）');
+  const sha = shortSha(T);
+  w(T, 'workflow/intents/2026-09-26-pe5.md', INTENT('pe5', '状态: done\n级别: L1\n日期: 2026-09-26', `\n## 验收标准（可测试）\n- [x] 演练穿越（证据:${sha}）\n`));
+  const r = run(T);
+  check('git 基础设施异常:正常 git 零出账（防误报负例）', !outOf(r).includes('git 探测异常'), outOf(r));
+  check('git 基础设施异常:正常 git 行为不变（无标记无关提交仍拦证据无关）', r.status === 1 && outOf(r).includes('证据无关'), `exit=${r.status}\n${outOf(r)}`);
+  rmfix(T);
+}
 // ---- 场景 45:检查 2——真未填占位（标题 <主题>，无 .md）→ 仍报模板未填 ----
 {
   const T = mkfix();