agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/scripts/check-scope-range.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// check-scope-range.mjs — 推送范围（old..new）级 plan 改动面对账（2026-11-09 建，check-scope 的推送执法版）
+// 用途：pre-push 对一次推送的整段 commit 范围对账——收集范围内新增/修改的 workflow/plans/*.md，
+//   并集提取各 plan 声明文件（extractDeclared 与 check-scope.mjs 单源复用），与范围 diff 对账。
+// 语义与红线：只读裁决（判红绿，不改任何状态）。
+//   - 只判越界方向（改了未声明）= hard；未落件（声明未改）仅 advisory 打印——多任务合推时声明先行、
+//     代码后推是合法节奏，硬判未落件必误报。
+//   - 范围内无 plan 新增/修改 → skip（exit 0）：该推送不携带新承诺，沿用提交时刻 check-confirm-order 执法。
+//   - 盲面封堵（2026-11-10）：skip 前补 advisory——范围含产品面改动（判据单源复用 verify-scope.mjs
+//     PRODUCT_FACES/classifyFace，再扣 AGENTS.md 引擎面：.agents/.zcode/.githooks/宿主适配/workflow/wiki/
+//     根 package.json/azure-pipelines.yml）且无 intent/spec 立档变更 → 打警告，exit 码不变、--strict 不升硬。
+//     事故线豁免（降级口径）：范围内有 incident 立档（非 INDEX 计数）变更 → 警告降级为提示——事故线合法无 plan。
+//     L0 豁免（降级口径，2026-11-11）：产品件全部来自 L0 极简道提交 → 警告降级为提示——L0 合法无 plan。
+//   - L0 极简道豁免（2026-11-11）：越过界对账同样认 L0。逐提交读消息，含非空 `L0: <判据>` 行且该提交
+//     产品路径 ≤5（判据单源复用 check-confirm-order.mjs：l0JudgementFromText / isProductPath / L0_MAX）
+//     → 该提交的产品路径不进越界集。缺失此通道时「plan 提交 + L0 提交」合推会把 L0 产品件判越界，
+//     --strict 直接拦推（L0 本就合法无 plan）。合并提交不给豁免（提交时刻 isMergeLike 同样跳过 L0 判定）。
+//     豁免按文件计且须独占：文件另被非 L0 提交（含合并提交）碰过即失豁免，防越界件搭 L0 便车。
+//   - plan 在工作区不可读 → exit 2（fail-loud，不静默放行；推送范围内改过的 plan 应已在工作区）。
+//   - old 全零（新分支首推）→ skip（exit 0）：范围判不出时不把整段历史误判越界。
+//   - --strict 时越界件非空 exit 1；默认 advisory（exit 0 出报告）。
+// 白名单与宽松匹配规则与 check-scope.mjs 单源（import 复用，不复制正则）。
+// 用法：node .agents/scripts/check-scope-range.mjs <oldSha> <newSha> [--strict] [--root <dir>]
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { extractDeclared, WHITELIST_RE, matches } from './check-scope.mjs';
+import { classifyFace } from './verify-scope.mjs';
+import { L0_MAX, isProductPath, l0JudgementFromText } from '../hooks/check-confirm-order.mjs';
+
+const args = process.argv.slice(2);
+let oldSha = '', newSha = '', strict = false, rootArg = '';
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--strict') strict = true;
+  else if (a === '--root') rootArg = args[++i] || '';
+  else if (!oldSha && !a.startsWith('--')) oldSha = a;
+  else if (!newSha && !a.startsWith('--')) newSha = a;
+}
+const ROOT = path.resolve(rootArg || process.cwd());
+if (!oldSha || !newSha) { console.error('用法: node .agents/scripts/check-scope-range.mjs <oldSha> <newSha> [--strict] [--root <dir>]'); process.exit(2); }
+
+const norm = (p) => p.replace(/\\/g, '/');
+
+if (/^0+$/.test(oldSha)) {
+  console.log('▶ check-scope-range：old 全零（新分支首推），范围判不出——skip');
+  process.exit(0);
+}
+
+// 2026-11-10 修（合并提交实证）：`git diff old..new` 把 merge 带进来的目标分支整批变更也算「本范围改了」——
+// 那些文件由目标分支侧的 plan 声明，本地范围里没有对应 plan → 恒判越界，合并后永远推不上去
+// （实证：合入 develop 后 8 个文件被判越界，全是 develop 侧的任务产物）。
+// 改为逐提交取改动：普通提交取 diff-tree 全量；合并提交取 combined diff（`-c`，只出「与所有父都不同」的
+// 冲突解决件），被合入分支带来的文件天然不入集；合并中手工解冲突的文件仍会被计入。
+const gitOut = (args) => spawnSync('git', ['-c', 'core.quotepath=off', ...args], { cwd: ROOT, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+const revs = gitOut(['rev-list', '--first-parent', '--reverse', `${oldSha}..${newSha}`]);
+if (revs.status !== 0) { console.error(`check-scope-range: git rev-list 失败: ${revs.stderr}`); process.exit(2); }
+// L0 豁免（2026-11-11）：一次性取范围内提交消息，逐提交判 `L0:` trailer 与该提交产品路径数。
+// 取不到消息 → 空表 → 不给豁免（fail-closed，与提交时刻「无消息文件豁免不生效」同口径）。
+const msgs = gitOut(['log', '--first-parent', '--reverse', '--format=%x1e%H%x00%B', `${oldSha}..${newSha}`]);
+const msgBySha = new Map();
+for (const rec of (msgs.status === 0 ? msgs.stdout : '').split('\x1e').filter((r) => r.trim())) {
+  const cut = rec.indexOf('\x00');
+  if (cut > 0) msgBySha.set(rec.slice(0, cut).trim(), rec.slice(cut + 1));
+}
+const changedSet = new Set();
+const l0ExemptSet = new Set();
+const nonL0Touched = new Set();
+for (const sha of revs.stdout.split(/\r?\n/).filter(Boolean)) {
+  const parents = gitOut(['rev-list', '--parents', '-n', '1', sha]).stdout.trim().split(/\s+/).slice(1);
+  const dt = parents.length > 1
+    ? gitOut(['diff-tree', '-c', '--no-commit-id', '--name-only', '--no-renames', '-r', sha])
+    : gitOut(['diff-tree', '--no-commit-id', '--name-only', '--no-renames', '-r', sha]);
+  if (dt.status !== 0) { console.error(`check-scope-range: git diff-tree 失败（${sha}）: ${dt.stderr}`); process.exit(2); }
+  const files = dt.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map(norm);
+  for (const f of files) changedSet.add(f);
+  // 合并提交不适用 L0：提交时刻 isMergeLike 会让 check-confirm-order 整条跳过，L0 豁免未被授予。
+  let granted = false;
+  if (parents.length === 1) {
+    const l0 = l0JudgementFromText(msgBySha.get(sha));
+    const products = files.filter(isProductPath);
+    granted = Boolean(l0) && products.length > 0 && products.length <= L0_MAX;
+    if (granted) for (const p of products) l0ExemptSet.add(p);
+  }
+  // 同一文件只要被任一非 L0 提交（含合并提交）碰过，就不享受豁免——否则非 L0 提交的越界件
+  // 可借同范围另一笔 L0 提交搭车洗白（豁免按文件计，不能只按提交计）。
+  if (!granted) for (const f of files) nonL0Touched.add(f);
+}
+for (const f of nonL0Touched) l0ExemptSet.delete(f);
+const changed = [...changedSet];
+
+// 盲面封堵（2026-11-10）辅助判定（只服务下方 skip 路径的 advisory，不改越界对账）：
+//   - 引擎面 = AGENTS.md 引擎面豁免清单 + wiki 豁免：其变更不算产品面，纯引擎面推送不触警告。
+//     PRODUCT_FACES 的后缀兜底（.cs/.sql 等）会把 wiki/数据维护 SQL 判进 backend 面——引擎面剔除优先，防纯 wiki 推送误警。
+//   - intent/spec 立档：workflow/{intents,specs} 下的 .md（INDEX 计数不算——目录索引维护不构成「有计划」）。
+//   - incident 立档：workflow/incidents 下的 .md（INDEX 计数不算——防搭车豁免）。
+const ENGINE_FACE_RE = /^(?:\.agents|\.zcode|\.githooks|\.opencode|\.trae|\.codebuddy|\.qwen|wiki|workflow)\//i;
+const ENGINE_FILE_RE = /^(?:azure-pipelines\.yml|package\.json)$/i;
+const isIntentSpecDoc = (f) => /^workflow\/(?:intents|specs)\/.+\.md$/i.test(f) && !f.endsWith('/INDEX.md');
+const isIncidentDoc = (f) => /^workflow\/incidents\/.+\.md$/i.test(f) && !f.endsWith('/INDEX.md');
+
+// 范围内新增/修改的 plan（删除的 plan 不构成承诺来源；plans 目录外不看）
+const plansInRange = changed.filter((f) => /^workflow\/plans\/.+\.md$/i.test(f) && !f.endsWith('/INDEX.md'));
+if (!plansInRange.length) {
+  console.log('▶ check-scope-range：推送范围无 plan 新增/修改——skip（提交时刻顺序门已执法）');
+  // 盲面封堵：范围零 plan 变更 ≠ 范围无事——多提交无 plan 合推可整段夹带产品面改动（提交时刻
+  // check-confirm-order 只看单条提交，原样静默 skip 即漏过）。只补 advisory：打印不拦截，exit 码不变，
+  // --strict 不升硬（与既有「未落件仅 advisory」同级）。产品面判据单源复用 verify-scope.mjs
+  // PRODUCT_FACES（backend/frontend 面 match，含 tests/、scripts/verify/backend/ 与后缀兜底）。
+  const productFace = classifyFace(changed).matched.filter((f) => !ENGINE_FACE_RE.test(f) && !ENGINE_FILE_RE.test(f));
+  if (productFace.length && !changed.some(isIntentSpecDoc)) {
+    const l0Face = productFace.filter((f) => l0ExemptSet.has(f));
+    const restFace = productFace.filter((f) => !l0ExemptSet.has(f));
+    if (changed.some(isIncidentDoc)) {
+      // 事故线豁免（降级口径）：有 incident 立档 → 产品改动按事故线处理（合法无 plan），不要求回填
+      // plan；降级为提示而非完全静默——立档与产品改动无关的搭车推送仍留观察面。
+      console.log('⚠（降级）推送含产品面改动且范围内无 plan 变更——范围内有 incident 立档，按事故线豁免；advisory 不拦截');
+    } else if (restFace.length === 0) {
+      // L0 豁免（降级口径）：产品件全部来自满足 trailer + ≤5 的 L0 提交——L0 合法无 plan，
+      // 与事故线同级降级为提示；混入非 L0 产品件时仍走下方回填警告。
+      console.log('⚠（降级）推送含产品面改动且范围内无 plan 变更——产品件全部来自 L0 极简道提交，按 L0 豁免；advisory 不拦截');
+    } else {
+      console.log('⚠ 推送含产品面改动但范围内无 plan 变更——若属计划外改动请先回填 plan（事故线 incident / L0 极简道除外）；本警告 advisory，不拦截');
+    }
+    console.log(`  产品面件 ${productFace.length}${l0Face.length ? `（其中 L0 豁免 ${l0Face.length}）` : ''}：${productFace.join('、')}`);
+  }
+  process.exit(0);
+}
+
+const declared = [];
+for (const rel of plansInRange) {
+  const abs = path.join(ROOT, rel);
+  if (!fs.existsSync(abs)) { console.error(`check-scope-range: plan 不可读: ${rel}`); process.exit(2); }
+  declared.push(...extractDeclared(abs));
+}
+
+// L0 极简道提交的产品路径不进越界集（提交时刻已由 check-confirm-order 豁免 A 放行，推送侧同口径）。
+const outOfScope = changed.filter((f) => !l0ExemptSet.has(f) && !WHITELIST_RE.test(f) && !declared.some((df) => matches(f, df)));
+const notLanded = declared.filter((df) => !changed.some((f) => matches(f, df)));
+
+console.log(`▶ check-scope-range（推送范围 plan 改动面对账）: ${oldSha.slice(0, 8)}..${newSha.slice(0, 8)}`);
+console.log(`  范围 plan ${plansInRange.length} 份（${plansInRange.join('、')}）｜ 声明 ${declared.length} ｜ 变更 ${changed.length}${l0ExemptSet.size ? ` ｜ L0 豁免 ${l0ExemptSet.size}` : ''}`);
+if (outOfScope.length) {
+  console.log('  越界件（推送改了但范围内 plan 未声明）:');
+  outOfScope.forEach((f) => console.log(`    - ${f}`));
+}
+if (notLanded.length) {
+  console.log('  未落件（声明未变更，advisory——多任务合推不硬判）:');
+  notLanded.forEach((f) => console.log(`    - ${f}`));
+}
+if (!outOfScope.length && !notLanded.length) console.log('  双向对齐 ✅');
+else if (!outOfScope.length) console.log('  越界方向干净 ✅（未落件仅 advisory）');
+else if (!strict) console.log('  （advisory 报告——--strict 时越界件即 fail）');
+
+if (strict && outOfScope.length) process.exit(1);
+process.exit(0);

package/templates/engine/.agents/scripts/check-scope.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// check-scope.mjs — plan 改动面 ↔ git 变更双向对账（2026-10-09，/goal 控制改动范围边界）
+// 用途：解析 plan「改动面 / 任务拆解 / 改动方案」节声明的文件清单，与 git 变更集对账——
+//   越界件（改了未声明）= 范围蔓延信号；未落件（声明未改）= plan 滞后或改名信号。检查 8 的证据对账
+//   只做单向交集（提交须触及至少一个声明文件），夹带 plan 外文件不报——本件补越界方向。
+// 语义与红线：只读裁决（判红绿，不改任何状态——命名规约 check- 前缀）；默认 advisory（exit 0 出报告），
+//   --strict 时越界件非空 exit 1（供门禁化调用方使用）；plan 不可读 exit 2（fail-loud，不静默放行）。
+//   文件匹配沿检查 8 宽松规则（f===df / 后缀 / 双向 includes）——声明粒度粗（写目录或部分路径）不误报越界；
+//   白名单豁免：workflow/ 台账（intents/specs/plans/incidents/INDEX）、.agents/confirmations.jsonl、
+//   .agents/confirmations.d/ 分片、package-lock.json——闭环随行件不算越界。
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+// 用法：node .agents/scripts/check-scope.mjs workflow/plans/<name>.md [--base <sha>|--staged] [--strict] [--root <dir>]
+//   默认比对工作区（含未跟踪，git status --porcelain 口径）；--base <sha> 比对 sha..HEAD 已提交变更；
+//   --staged 仅比对暂存区。
+// 沿革：2026-10-09 立档（缺口实证=检查 8 单向交集不拦夹带）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// 声明文件提取——与 check-loop 检查 8 同节同正则（改动面|任务拆解|改动方案），另加扩展名白名单
+// （过滤 v1.2.2 之类版本号伪 token：无目录且扩展名不在清单内则弃）
+// 2026-11-09 抽为导出函数：推送级对账 check-scope-range.mjs 复用，正则单源不复制第三份。
+// 2026-11-10 修：①原先每行只取首个路径（`line.match`），一行并列两三个文件时后续文件全成「未声明」——
+//   推送实证（2026-11-10-outbound-request-line-material-check-stamp：`…OutboundRequestDetail.cs`；
+//   `…MaterialDbContext.cs` 同行）被判越界；②补扫「验证计划」节——新增测试文件常只在该节点名
+//   （推送实证：outbound-request-check-satisfaction-display 的 `…OutboundRequestCheckSatisfactionTests.cs`），
+//   计划点名即算声明，产品面判据本身不放宽。
+export const KNOWN_EXT = new Set(['.md', '.mjs', '.js', '.ts', '.json', '.txt', '.cs', '.csproj', '.sln', '.vue', '.ps1', '.sh', '.yml', '.yaml', '.sql', '.cjs']);
+export function extractDeclared(planAbs) {
+  const declared = [];
+  const lines = fs.readFileSync(planAbs, 'utf8').split(/\r?\n/);
+  let inSec = false;
+  for (const line of lines) {
+    if (/^##\s+(改动面|任务拆解|改动方案|验证计划)/.test(line)) { inSec = true; continue; }
+    if (inSec && /^##\s+/.test(line)) { inSec = false; continue; }
+    if (!inSec) continue;
+    for (const m of line.matchAll(/([a-zA-Z0-9._\/\\-]+\.[a-zA-Z0-9]+)/g)) {
+      const tok = m[1].replace(/\\/g, '/');
+      const ext = tok.slice(tok.lastIndexOf('.'));
+      if (tok.includes('/') || KNOWN_EXT.has(ext.toLowerCase())) declared.push(tok);
+    }
+  }
+  return declared;
+}
+
+// 白名单与宽松匹配规则同为共享常量（check-scope-range 复用，口径单源）
+// 2026-11-10 扩容（推送实证：L1 关单单笔提交恒判越界，与 new-task.md §L1「plan(done) + 代码 + 确认分片 +
+// verify 凭证同一笔入库」互斥）：按 AGENTS.md「引擎面豁免 / wiki 豁免」口径补三类非产品面——
+//   ① 引擎面：.agents/ 全部、.zcode/、.githooks/、宿主适配目录、azure-pipelines.yml、根 AGENTS.md；
+//   ② 台账与凭证：workflow/ 根级台账（delegations.md / regression-checklist.md / reviews.md / papercuts.md /
+//      metrics.md / verify-evidence.md）、其 .d/ 月度分片、本机证据目录 workflow/evidence/（gitignore 排除）；
+//   ③ wiki 知识文档（内容调整同享豁免；删除 wiki 文件仍须单独指令，不由此门放开）。
+// 产品面（backend / frontend/src / tests / 数据维护 SQL）判据不变：改了未声明仍 hard。
+export const WHITELIST_RE = /^(?:workflow\/(?:intents|specs|plans|incidents)\/|workflow\/INDEX\.md$|workflow\/[^/]+\.md$|workflow\/[^/]+\.d\/|workflow\/evidence\/|wiki\/|\.agents\/|\.zcode\/|\.githooks\/|\.opencode\/|\.trae\/|\.codebuddy\/|\.qwen\/|azure-pipelines\.yml$|AGENTS\.md$|package-lock\.json$)/;
+export const matches = (f, df) => f === df || f.endsWith(`/${df}`) || f.includes(df) || df.includes(f);
+const norm = (p) => p.replace(/\\/g, '/');
+
+function main() {
+const args = process.argv.slice(2);
+let planRel = '', base = '', staged = false, strict = false, rootArg = '';
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--base') base = args[++i] || '';
+  else if (a === '--staged') staged = true;
+  else if (a === '--strict') strict = true;
+  else if (a === '--root') rootArg = args[++i] || '';
+  else if (!planRel && !a.startsWith('--')) planRel = a;
+}
+const ROOT = path.resolve(rootArg || process.cwd());
+if (!planRel) { console.error('用法: node .agents/scripts/check-scope.mjs workflow/plans/<name>.md [--base <sha>|--staged] [--strict] [--root <dir>]'); process.exit(2); }
+const planAbs = path.isAbsolute(planRel) ? planRel : path.join(ROOT, planRel);
+if (!fs.existsSync(planAbs)) { console.error(`plan 不可读: ${planRel}`); process.exit(2); }
+
+const declared = extractDeclared(planAbs);
+
+const git = (gitArgs, opts = {}) => spawnSync('git', gitArgs, { cwd: ROOT, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, ...opts });
+let changed = [];
+if (base) {
+  const r = git(['diff', '--name-only', `${base}..HEAD`]);
+  if (r.status !== 0) { console.error(`git diff 失败: ${r.stderr}`); process.exit(2); }
+  changed = r.stdout.split(/\r?\n/).filter(Boolean);
+} else if (staged) {
+  const r = git(['diff', '--name-only', '--cached']);
+  if (r.status !== 0) { console.error(`git diff 失败: ${r.stderr}`); process.exit(2); }
+  changed = r.stdout.split(/\r?\n/).filter(Boolean);
+} else {
+  // 工作区口径：status --porcelain -uall（含未跟踪且逐文件展开——默认折叠成 `?? dir/` 会把整个新目录误判越界）
+  const r = git(['status', '--porcelain', '-uall']);
+  if (r.status !== 0) { console.error(`git status 失败: ${r.stderr}`); process.exit(2); }
+  changed = r.stdout.split(/\r?\n/).filter(Boolean).map((l) => {
+    const body = l.slice(3);
+    const ren = body.match(/.* -> (.*)$/); // 重命名取新路径
+    return (ren ? ren[1] : body).trim().replace(/^"(.*)"$/, '$1');
+  });
+}
+
+const outOfScope = changed.filter((f) => !WHITELIST_RE.test(norm(f)) && !declared.some((df) => matches(norm(f), df)));
+const notLanded = declared.filter((df) => !changed.some((f) => matches(norm(f), df)));
+
+console.log(`▶ check-scope（plan 改动面 ↔ git 变更对账）: ${planRel}`);
+console.log(`  声明 ${declared.length} ｜ 变更 ${changed.length}${base ? `（${base}..HEAD）` : staged ? '（staged）' : '（工作区）'}`);
+if (outOfScope.length) {
+  console.log('  越界件（改了未声明）:');
+  outOfScope.forEach((f) => console.log(`    - ${f}`));
+}
+if (notLanded.length) {
+  console.log('  未落件（声明未变更）:');
+  notLanded.forEach((f) => console.log(`    - ${f}`));
+}
+if (!outOfScope.length && !notLanded.length) console.log('  双向对齐 ✅');
+else if (!strict) console.log('  （advisory 报告——--strict 时越界件即 fail）');
+
+if (strict && outOfScope.length) process.exit(1);
+process.exit(0);
+}
+
+// 直接执行才跑 CLI；被 check-scope-range.mjs import 时只取共享函数/常量
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  main();
+}

package/templates/engine/.agents/scripts/check-scripts-syntax.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// check-scripts-syntax.mjs — 引擎脚本语法自检（node --check；本地增量，全量需手动 CHECK_LOOP_FULL=1）
+// 用途：守护者受守护——对 .agents/scripts 与 .agents/hooks 下全部 .mjs/.cjs 逐个 node --check，
+//       任何文件不可解析即判红（先例教训：verify.mjs:31 SyntaxError 带病进 CI，全链门静默失效）。
+// 2026-10-28 引擎减重第三刀：默认只检「本轮 diff 触及的引擎脚本」（.agents/scripts/.agents/hooks/
+//   scripts/verify 面）；CHECK_LOOP_FULL=1（本地手动，CI 不跑治理门）或显式传目录 → 全量。目录存在性/空目录 fail-closed
+//   检查仍按全量目录做，防「改名/删除/清空即去门」。
+// 语义与红线：只读裁决，不改任何状态；**任一**检查目录缺失、或该目录递归后一个可检文件都没有，
+// 一律判红（fail-closed）；递归扫描（2026-10-24 复核 M1：原实现只 readdirSync 顶层，
+// `scripts/verify` 顶层 0 个 .mjs 时静默空转、总数不变无痕迹）；不 import 任何引擎件，零依赖可独立调度。
+// 性能（scripts-syntax-parallel）：node --check 无原地解析 ESM 的 API，只能逐文件起子进程
+//       （单次 ~70ms × 117 文件）；改工作池并发（min(8, cpus-2)）后本机 8.1s → 4.2s，判红集合不变。
+// 用法：node .agents/scripts/check-scripts-syntax.mjs [目录...]（相对仓库根；缺省 .agents/scripts .agents/hooks
+//       scripts/verify——第三项为 backend 门执行器所在，2026-10-24 复核 P1 修复纳入守护；
+//       CHECK_LOOP_ROOT 可覆写仓库根，与 check-loop/verify 同口径）
+// 沿革：guardian-selfcheck（审计 P0-1 立项，verify.mjs GATES 首门消费）。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn, execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
+const DEFAULT_DIRS = ['.agents/scripts', '.agents/hooks', 'scripts/verify'];
+// 项目侧目录：不存在时跳过（新装户可能没有 scripts/verify）；存在但为空仍 fail-closed。
+const OPTIONAL_DIRS = new Set(['scripts/verify']);
+
+const dirs = process.argv.slice(2);
+const targets = dirs.length ? dirs : DEFAULT_DIRS;
+
+// 守卫文件清单（目录缺失 fail-closed；**每目录**可检文件数 0 fail-closed——防「改名/删除/清空即去门」）
+const SKIP_DIRS = new Set(['node_modules', '.git', 'tmp']); // tmp = 一次性/生成件（gitignored），不入守护面
+const walk = (abs, rel) => {
+  const out = [];
+  for (const ent of fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (ent.isSymbolicLink()) continue; // 防环；符号链接目标不属本仓守护面
+    const childAbs = path.join(abs, ent.name);
+    const childRel = `${rel}/${ent.name}`;
+    if (ent.isDirectory()) { if (!SKIP_DIRS.has(ent.name)) out.push(...walk(childAbs, childRel)); continue; }
+    if (ent.isFile() && /\.(mjs|cjs)$/.test(ent.name)) out.push({ rel: childRel, abs: childAbs });
+  }
+  return out;
+};
+
+const files = [];
+const missing = [];
+const empty = [];
+for (const d of targets) {
+  const abs = path.resolve(ROOT, d);
+  try {
+    if (!fs.statSync(abs).isDirectory()) { missing.push(d); continue; }
+  } catch {
+    if (OPTIONAL_DIRS.has(d)) continue;
+    missing.push(d);
+    continue;
+  }
+  const found = walk(abs, d);
+  if (!found.length) { empty.push(d); continue; }
+  files.push(...found);
+}
+
+// 增量面（2026-10-28 第三刀）：默认只检本轮 diff 触及的脚本；CHECK_LOOP_FULL=1 / 显式传目录 /
+// 夹具根（CHECK_LOOP_ROOT）→ 全量。目录存在性检查仍按全量目录做（防去门）。
+const explicitDirs = dirs.length > 0;
+const FULL = process.env.CHECK_LOOP_FULL === '1' || explicitDirs || !!process.env.CHECK_LOOP_ROOT;
+let changed = null;
+if (!FULL) {
+  const gitOut = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch {
+      return '';
+    }
+  };
+  const set = new Set();
+  const add = (text) => String(text || '').split(/\r?\n/).forEach((l) => {
+    const p = l.trim().replace(/\\/g, '/');
+    if (/\.(mjs|cjs)$/.test(p)) set.add(p);
+  });
+  add(gitOut(['diff', '--name-only', '--no-renames', 'HEAD'])); // HEAD..工作区（含暂存）
+  add(gitOut(['ls-files', '--others', '--exclude-standard']));  // untracked 新脚本
+  changed = set;
+}
+const checked = changed ? files.filter((f) => changed.has(f.rel)) : files;
+const total = checked.length;
+
+// node --check 逐文件起子进程（无 API 可原地解析 ESM 而不执行），单次 ~70ms × 108 文件 = 8.1s 实测；
+// 工作池并发后墙钟 ≈ 单次 spawn × ceil(文件数/并发)（scripts-syntax-parallel）。
+// 裁决口径不变：任一文件不可解析即判红，判红文件按路径排序输出（并发下不回放乱序）。
+const reds = [];
+{
+  const conc = Math.max(2, Math.min(8, os.cpus().length - 2));
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < checked.length) {
+      const t = checked[cursor++];
+      const r = await new Promise((resolve) => {
+        const child = spawn(process.execPath, ['--check', t.abs]);
+        let err = '';
+        child.stderr.on('data', (d) => { err += d; });
+        child.on('error', (e) => resolve({ status: null, stderr: String(e.message) }));
+        child.on('close', (status) => resolve({ status, stderr: err }));
+      });
+      if (r.status !== 0) {
+        const first = (r.stderr || '').split(/\r?\n/).find((l) => l.trim()) || `exit ${r.status}`;
+        reds.push(`[syntax] ❌ ${t.rel}: ${first}`);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(conc, checked.length) }, worker));
+  reds.sort();
+}
+
+if (missing.length) {
+  console.error(`[syntax] ❌ 检查目标目录缺失：${missing.join('、')}（fail-closed——脚本被改名/删除即去门）`);
+  process.exit(1);
+}
+if (empty.length) {
+  console.error(`[syntax] ❌ 检查目标目录递归后无可检脚本：${empty.join('、')}（fail-closed——目录被清空/改名即去门）`);
+  process.exit(1);
+}
+if (changed && total === 0) {
+  console.log(`[syntax] ✅ 本轮无引擎脚本变更（增量；全量 ${files.length} 个脚本请用 CHECK_LOOP_FULL=1）`);
+  process.exit(0);
+}
+if (total === 0) {
+  console.error('[syntax] ❌ 可检文件数为 0（目录为空或参数指错，fail-closed）');
+  process.exit(1);
+}
+if (reds.length) {
+  for (const line of reds) console.error(line);
+  console.error(`[syntax] 共 ${total} 个引擎脚本，${reds.length} 个不可解析`);
+  process.exit(1);
+}
+console.log(`[syntax] ✅ ${total} 个引擎脚本全部可解析（node --check${changed ? `；增量面，全量 ${files.length}` : ''}）`);
+process.exit(0);