agentic-flow-kit 1.1.9 → 1.2.1

package/package.json

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

package/templates/_agents/commands/test.md

@@ -75,7 +75,7 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 输出测试报告(通过项 / 失败项)
 - 失败项已修复并复测通过
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
 **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。

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

@@ -111,7 +111,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { loadEnums } from './workflow-enums.mjs';
 import { runCheck16 } from './check-metric-claims.mjs';
-import { auditEnabled, loadKitPolicy } from './policy.mjs';
+import { auditEnabled, loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
 import { laneOfEntry } from './stage-gates.mjs';
 // MARK_RE：incident 留痕形态的单源（第七轮复核 N3——此前 check-loop 内联复制一份同口径字面量，
 // 两处靠注释与人工同步；改为复用 stage-gates.mjs 的导出，从结构上消除漂移可能）
@@ -629,9 +629,22 @@ function warnEvidenceExempt(type, base) {
 }
 
 // 证据真相校验：检查证据字符串是否包含合法的 commit SHA，且该 commit 触及了 plan 声明的文件
-function verifyEvidenceTruth(evidenceStr, planBase, root) {
+// 测试绿声明对账（2026-10-07 verify-evidence）：ctx = { verifyRelevant, hasFresh } 时，无 SHA 且命中
+// 关键词的证据走凭证对账——有 24h 绿行 → verify 型豁免出账；无 → verify-missing（聚合段出 warning，
+// 灰度第一档非 blocker）。ctx 由调用方按「intent 加入 git ≥ verifySince（v5 锚）」组装；锚不可判定
+// → ctx null → 维持 text 豁免（无判定依据不产出告警）。关键词表最小集起步（check2-datetime 先例：
+// 只豁免实证形态，变体实证再扩）。
+const VERIFY_GREEN_RE = /测试通过|测试全绿|测试绿|全绿/;
+function verifyEvidenceTruth(evidenceStr, planBase, root, ctx) {
   const shaMatch = evidenceStr.match(/\b([a-f0-9]{7,40})\b/i);
   if (!shaMatch) {
+    if (ctx && ctx.verifyRelevant && VERIFY_GREEN_RE.test(evidenceStr)) {
+      if (ctx.hasFresh) {
+        warnEvidenceExempt('verify', planBase);
+        return { ok: true, type: 'verify' };
+      }
+      return { ok: true, type: 'verify-missing' };
+    }
     warnEvidenceExempt('text', planBase);
     return { ok: true, type: 'text' };
   }
@@ -711,6 +724,15 @@ function verifyEvidenceTruth(evidenceStr, planBase, root) {
 {
   const accCutoff = '2026-09-12';
   let legacyUnaccounted = 0;
+  // 测试绿凭证状态（2026-10-07 verify-evidence）：台账读一次循环外缓存；policy 缺 verifySince
+  //（v1-v4）→ ctxBase null → 对账整体跳过（向后兼容）
+  const verifySinceOf = kitPolicy.verifySince;
+  const verifyFresh = (() => {
+    try {
+      const vp = path.join(ROOT, '.agents', 'verifications.jsonl');
+      return fs.existsSync(vp) ? hasFreshVerifyLine(fs.readFileSync(vp, 'utf8').split(/\r?\n/)) : false;
+    } catch { return false; }
+  })();
   for (const intent of docFiles('intents')) {
     if (fmGet(intent, '状态') !== 'done') continue;
     const base = path.basename(intent);
@@ -761,9 +783,17 @@ function verifyEvidenceTruth(evidenceStr, planBase, root) {
     //（豁免通道不得独立成立，防「只引 docs 提交洗白代码改动」）。
     if (evidenceItems.length) {
       const planBase = base.replace(/.md$/, '');
-      const results = evidenceItems.map((ev) => ({ t: verifyEvidenceTruth(ev, planBase, ROOT) }));
+      // verify 对账 ctx：intent 首次加入 git ≥ verifySince（v5 锚）才参与；不可判定 → null 走 text 豁免
+      const iadd = addedDateOf(intent);
+      const vctx = typeof verifySinceOf === 'string' && iadd !== '' && iadd >= verifySinceOf
+        ? { verifyRelevant: true, hasFresh: verifyFresh } : null;
+      const results = evidenceItems.map((ev) => ({ t: verifyEvidenceTruth(ev, planBase, ROOT, vctx) }));
       const hasImplEvidence = results.some((r) => r.t.ok && (r.t.type === 'sha' || r.t.type === 'process'));
       for (const r of results) {
+        if (r.t.ok && r.t.type === 'verify-missing') {
+          warnings.push(`- [WARN 测试绿缺凭证] ${base} 验收证据声明「测试绿」但 24h 内无 verify 凭证（verifications.jsonl）——跑 node .agents/scripts/verify.mjs 后重跑（advisory，灰度第一档）`);
+          continue;
+        }
         if (r.t.ok) continue;
         if (r.t.type === 'irrelevant' && r.t.recordCommit && hasImplEvidence) {
           warnEvidenceExempt('record', planBase);

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

@@ -2662,5 +2662,46 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   rmfix(T2);
 }
 
+// ---- 场景:检查 8 测试绿声明对账（2026-10-07 verify-evidence）——v5 锚后无 SHA「测试绿」声明须有凭证 ----
+{
+  // 配对构造（检查 15 须过）：approved 态全文算指纹 → done 态落盘 + 台账 done 行（prev=approved，
+  // ts=今天 ≥ bindingTs）——与 bindingSha256 复原口径对称
+  const mkVe = (withLedger) => {
+    const T = mkfix();
+    gitInit(T);
+    w(T, '.agents/kit.json', JSON.stringify({ policyVersion: 5 }));
+    if (withLedger) {
+      w(T, '.agents/verifications.jsonl', `${JSON.stringify({ ts: new Date().toISOString(), exitCode: 0, suite: 'npm test' })}\n`);
+    }
+    const iBody = '# INTENT — ve\n\n## 验收标准（可测试）\n- [x] 用例通过（证据:测试全绿）\n';
+    const pBody = '# PLAN — ve\n';
+    const fpI = computeFingerprint(`---\n状态: approved\n级别: L1\n日期: 2026-10-07\n---\n${iBody}`);
+    const fpP = computeFingerprint(`---\n状态: approved\n级别: L1\n---\n${pBody}`);
+    w(T, 'workflow/intents/2026-10-07-ve.md', `---\n状态: done\n级别: L1\n日期: 2026-10-07\n确认指纹: ${fpI.slice(0, 16)}\n---\n${iBody}`);
+    w(T, 'workflow/plans/2026-10-07-ve.md', `---\n状态: done\n级别: L1\n确认指纹: ${fpP.slice(0, 16)}\n---\n${pBody}`);
+    const now = new Date().toISOString();
+    writeLedger(T, [
+      { ts: now, doc: 'workflow/intents/2026-10-07-ve.md', stage: 'done', fingerprint: fpI, prev: 'approved' },
+      { ts: now, doc: 'workflow/plans/2026-10-07-ve.md', stage: 'done', fingerprint: fpP, prev: 'approved' },
+    ]);
+    gitCommitAll(T, 'feat: ve fixture');
+    return T;
+  };
+  // ① 无凭证 → warning（advisory，不拦 exit）
+  const T1 = mkVe(false);
+  let r = run(T1);
+  check('检查 8 凭证对账:锚后「测试绿」声明无凭证 → warning 且不 hard',
+    r.status === 0 && outOf(r).includes('测试绿缺凭证') && !outOf(r).includes('证据伪造') && !outOf(r).includes('证据无关'),
+    `exit=${r.status}\n${outOf(r)}`);
+  rmfix(T1);
+  // ② 有近期绿行 → verify 型豁免出账、零 warning
+  const T2 = mkVe(true);
+  r = run(T2);
+  check('检查 8 凭证对账:24h 内有绿行 → verify 豁免出账且无 warning',
+    r.status === 0 && outOf(r).includes('证据豁免 verify') && !outOf(r).includes('测试绿缺凭证'),
+    `exit=${r.status}\n${outOf(r)}`);
+  rmfix(T2);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/confirm-doc.mjs

@@ -40,7 +40,19 @@ import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { loadKitPolicy } from './policy.mjs';
+import { loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
+
+// hasFreshVerify(root)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
+// policy.hasFreshVerifyLine）。只读，台账缺失/不可读一律 false（=无凭证，advisory 层 fail-open）。
+function hasFreshVerify(root) {
+  try {
+    const p = path.join(root, '.agents', 'verifications.jsonl');
+    if (!fs.existsSync(p)) return false;
+    return hasFreshVerifyLine(fs.readFileSync(p, 'utf8').split(/\r?\n/));
+  } catch {
+    return false;
+  }
+}
 
 // computeFingerprint(text)：CRLF 归一 → 剔指纹行 → sha256 hex（64 位）
 export function computeFingerprint(text) {
@@ -304,6 +316,14 @@ if (isMain) {
         continue;
       }
     }
+    // 测试绿凭证前置（2026-10-07 verify-evidence，advisory 不拦）：→done 且文档含「验收标准」节且
+    // policy v5（verifySince）→ 24h 窗口内须有 verifications.jsonl 绿行。只读判定，任何读取异常降级
+    // 静默（fail-open——advisory 层不因台账缺失/坏行阻断关单）；升 hard 走后续 policyVersion 演进。
+    if (target === 'done' && typeof loadKitPolicy(root).verifySince === 'string'
+      && /^##\s*[^#]*验收标准/m.test(text) && !hasFreshVerify(root)) {
+      console.error(`⚠️ ${doc} 置 done：24h 内无测试绿凭证（verifications.jsonl）——关单勾验的「测试绿」声明缺机器事实`);
+      console.error('   跑 node .agents/scripts/verify.mjs（全绿自动落账）后重新关单；本次不拦截（advisory，灰度第一档）');
+    }
     const fp = computeFingerprint(text);
     // AI 自治放行分支（2026-09-30 ai-autonomy-trust）：
     // ① 仅 L0/L1（读 frontmatter「级别」，缺级别按不可自治处理——fail-closed）；

package/templates/_agents/scripts/confirm-doc.test.mjs

@@ -700,5 +700,41 @@ const writeTrust = (root, cfg) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S38 测试绿凭证前置（2026-10-07 verify-evidence）：v5 + 验收节 + 无凭证 → ⚠️ advisory 且仍落账 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-verify1-'));
+  const docP = path.join(root, 'workflow', 'intents');
+  fs.mkdirSync(docP, { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({ policyVersion: 5 }), 'utf8');
+  fs.writeFileSync(path.join(docP, '2026-10-07-v.md'),
+    '---\n状态: approved\n级别: L1\n确认指纹: aaaa1111aaaa1111\n---\n# I\n\n## 验收标准（可测试）\n- [x] 用例通过（证据:测试全绿）\n', 'utf8');
+  const r = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-07-v.md', '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+  const after = fs.readFileSync(path.join(docP, '2026-10-07-v.md'), 'utf8');
+  check('S38 凭证前置：v5 + 验收节 + 无凭证 → ⚠️ 出账且 done 仍落态（advisory 不拦）',
+    r.status === 0 && /无测试绿凭证/.test(r.stderr) && /verify\.mjs/.test(r.stderr) && after.includes('状态: done'),
+    JSON.stringify({ status: r.status, stderr: String(r.stderr).slice(0, 200) }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S39 测试绿凭证前置：近期绿凭证在场 → 静默（无 ⚠️）----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-verify2-'));
+  const docP = path.join(root, 'workflow', 'intents');
+  fs.mkdirSync(docP, { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({ policyVersion: 5 }), 'utf8');
+  fs.writeFileSync(path.join(root, '.agents', 'verifications.jsonl'),
+    `${JSON.stringify({ ts: new Date().toISOString(), exitCode: 0, suite: 'npm test', passed: 1, failed: 0 })}\n`, 'utf8');
+  fs.writeFileSync(path.join(docP, '2026-10-07-w.md'),
+    '---\n状态: approved\n级别: L1\n确认指纹: bbbb2222bbbb2222\n---\n# I\n\n## 验收标准（可测试）\n- [x] 用例通过（证据:测试全绿）\n', 'utf8');
+  const r = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-07-w.md', '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+  const after = fs.readFileSync(path.join(docP, '2026-10-07-w.md'), 'utf8');
+  check('S39 凭证前置：24h 内有绿行 → 静默（无 ⚠️）且 done 落态',
+    r.status === 0 && !/无测试绿凭证/.test(r.stderr) && after.includes('状态: done'),
+    JSON.stringify({ status: r.status, stderr: String(r.stderr).slice(0, 200) }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/pipeline-run.mjs

@@ -90,7 +90,9 @@ function runNode(ctx, run, script, args) {
   const scriptPath = path.join(ctx.bin, script);
   const cmd = `node .agents/scripts/${script} ${args.join(' ')}`;
   const t0 = Date.now();
-  const p = spawnSync(process.execPath, [scriptPath, ...args], { cwd: ctx.root, encoding: 'utf8', windowsHide: true });
+  // PIPELINE_RUN_ID 注入（2026-10-07 verify-evidence 复核 P2-1）：verify.mjs 绿行据此绑定 runId
+  //（对质链与 run 事件流同源，docsCommit 格式已含同一 runId）——spec「pipeline-run 路径自动绑定」落点
+  const p = spawnSync(process.execPath, [scriptPath, ...args], { cwd: ctx.root, encoding: 'utf8', windowsHide: true, env: { ...process.env, PIPELINE_RUN_ID: run.runId } });
   const ms = Date.now() - t0;
   const exit = p.status ?? 1;
   emit(run, { type: 'gate', cmd, exit, ms });

package/templates/_agents/scripts/policy.mjs

@@ -52,6 +52,23 @@ export const POLICIES = {
     bindingTs: '2026-09-28',
     delegationSince: '2026-10-06', // 检查 18 委派台账对账生效日（2026-10-06 loop-audit-remediation）；v1-v3 无此键 → 原全量对账行为
   },
+  // 版本 5 = 版本 2 的全部日期 + verifySince（测试绿机器凭证生效日，2026-10-07 verify-evidence）。
+  // 基准：Anthropic AI-Native SDLC「make test before done」。三处消费：verify.mjs 绿行落账（无开关，
+  // 纯事实记录）+ confirm-doc 置 done 门前置 advisory（24h 窗口）+ 检查 8 无 SHA 测试绿声明对账
+  // （intent 首次加入 git ≥ verifySince 才判）。缺键（v1-v4）→ 两处判定整体跳过，存量零新增告警。
+  // 注意本版本以 v2 为基线（本仓自用版本），不含 v3/v4 的装户后移锚——装户升 v5 视同同时接受
+  // v2 基线的早期锚（装户已选 v3/v4 的，升 v5 前 doctor 会提示锚变化，逐键核对后再升）。
+  5: {
+    moduleSince: '2026-09-22',
+    check14Since: '2026-09-26',
+    confirmDocsEffective: '2026-09-27',
+    confirmIncidentsEffective: '2026-09-28',
+    bindingTs: '2026-09-28',
+    check17UnclosedAfter: '0.8.0',
+    stageGateSince: '2026-09-29',
+    riskLevelSince: '2026-10-01',
+    verifySince: '2026-10-07', // 测试绿机器凭证生效日（2026-10-07 verify-evidence）；v1-v4 无此键 → 前置与对账整体跳过
+  },
 };
 
 export function loadKitPolicy(root) {
@@ -72,3 +89,22 @@ export function loadKitPolicy(root) {
 export function auditEnabled(policy) {
   return policy.audit !== false;
 }
+
+// ---- 测试绿凭证判定（2026-10-07 verify-evidence）----
+// 单源（confirm-doc done 前置与 check-loop 检查 8 对账共用——防两处窗口字面量漂移，N3 教训）：
+// hasFreshVerifyLine(lines, now)：verifications.jsonl 的行数组里是否存在「ts 距 now ≤ 24h 且
+// exitCode === 0」的绿行。坏行（非 JSON / 缺 ts）跳过不抛；窗口 24h = 覆盖「跑 verify → 跨会话/
+// 隔夜 → 次日关单」节奏（spec 2026-10-07-verify-evidence 论证）。
+export function hasFreshVerifyLine(lines, now = Date.now()) {
+  for (const line of lines || []) {
+    if (!line || !line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && e.exitCode === 0 && typeof e.ts === 'string') {
+        const t = Date.parse(e.ts);
+        if (Number.isFinite(t) && now - t <= 24 * 60 * 60 * 1000) return true;
+      }
+    } catch { /* 坏行容忍跳过（confirmations.jsonl 同口径） */ }
+  }
+  return false;
+}

package/templates/_agents/scripts/verify.mjs

@@ -1,28 +1,52 @@
 #!/usr/bin/env node
 // verify.mjs — 关单固定编排（2026-09-24 intent closeout-verify-script；2026-09-26 check-loop-node 第 2 步直连 node）
 // 用途：关单前一键过门——按写死顺序执行 npm test → check-loop，逐项输出 pass/fail。
-// 语义：只编排不裁决——两条命令都是既有门禁原样跑，本脚本不新增校验、不读配置、无状态；
-//   任一步非零即 fail-fast 退出 1，失败原因经 stdio inherit 原样透传不吞。
+// 语义：只编排不裁决——两条命令都是既有门禁原样跑，本脚本不读配置、不判窗口、不改退出码；
+//   任一步非零即 fail-fast 退出 1，失败原因原样透传不吞。
 //   check-loop 为 node 实现（经 check-loop.mjs 直跑——node 即本脚本运行时必然可用，
 //   旧「缺 sh 环境 fail-closed」分支随 sh 依赖消失退役）。
+// 凭证落账（2026-10-07 verify-evidence）：两步全绿后向 <root>/.agents/verifications.jsonl append
+//   一行机器事实 {ts, exitCode:0, suite, passed?, failed?, runId?}——append-only 事实记录，不属裁决
+//   （窗口判定/门禁在消费方 confirm-doc 与 check-loop 检查 8）；消费语义 = 「按门跑了 verify 且全绿」，
+//   裸跑 npm test 不落账（对齐引导）。npm test 步骤输出从 inherit 改 pipe 捕获后回放（延迟显示，
+//   关单场景可接受）——仅为 best-effort 抓「合计: PASS n / FAIL n」计数行，抓不到则省略计数键。
+// 装户仓（根目录无 package.json，工程在子目录）下默认 npm test 恒 ENOENT（exit 4058）→ **显式跳过步骤 1**
+// 且**不落测试绿凭证**（凭证语义 = 测试真跑绿，跳过即无凭证，防假绿），并提示用
+// --test-cmd "<项目测试命令>" 指定；显式 --test-cmd 不受此判定影响（2026-10-07 papercut）。
 // 测试：node templates/_agents/scripts/verify.test.mjs（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具，不触真实 npm test 与 workflow）
-// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"]（--test-cmd 仅供测试注入）
+// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"]（--test-cmd 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令）
+import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
-const testCmd = args.includes('--test-cmd') ? args[args.indexOf('--test-cmd') + 1] : 'npm test';
+const explicitTestCmd = args.includes('--test-cmd') ? args[args.indexOf('--test-cmd') + 1] : null;
+const testCmd = explicitTestCmd ?? 'npm test';
 const checkLoop = path.join(SCRIPT_DIR, 'check-loop.mjs');
+const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
 
-console.log(`[verify] ▶ 1/2 ${testCmd}`);
-const t = spawnSync(testCmd, { shell: true, stdio: 'inherit' });
-if (t.status !== 0) {
-  console.error(`[verify] ❌ 1/2 ${testCmd} 未通过（exit ${t.status ?? t.error?.code}）——修复后重跑，非绿不关单`);
-  process.exit(1);
+// 装户仓判定：默认命令只在**当前目录**有 package.json 时才跑（npm test 亦在该目录执行）。
+// 跳过时后续不落测试绿凭证（见文末落账段）。
+const hasRootPackageJson = fs.existsSync(path.join(process.cwd(), 'package.json'));
+const skipTest = explicitTestCmd === null && !hasRootPackageJson;
+let testStdout = '';
+
+if (skipTest) {
+  console.log('[verify] ⏭ 1/2 跳过 npm test：当前目录无 package.json（装户仓）——请按项目口径手工跑测试，或用 --test-cmd "<项目测试命令>" 指定后重跑');
+} else {
+  console.log(`[verify] ▶ 1/2 ${testCmd}`);
+  const t = spawnSync(testCmd, { shell: true, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  if (t.stdout) process.stdout.write(t.stdout);
+  if (t.stderr) process.stderr.write(t.stderr);
+  if (t.status !== 0) {
+    console.error(`[verify] ❌ 1/2 ${testCmd} 未通过（exit ${t.status ?? t.error?.code}）——修复后重跑，非绿不关单`);
+    process.exit(1);
+  }
+  testStdout = String(t.stdout || '');
+  console.log('[verify] ✅ 1/2 测试通过');
 }
-console.log('[verify] ✅ 1/2 测试通过');
 
 console.log('[verify] ▶ 2/2 check-loop');
 const c = spawnSync(process.execPath, [checkLoop], { stdio: 'inherit' });
@@ -31,4 +55,22 @@ if (c.status !== 0) {
   process.exit(1);
 }
 console.log('[verify] ✅ 2/2 闭环校验通过');
+
+// 凭证落账：两步全绿才落（check-loop 红不产生凭证——凭证语义 = verify 全绿）；**步骤 1 被跳过同样不落**
+// （测试未跑即无「测试绿」事实，落账即假绿）；IO 失败出账不阻断
+try {
+  if (skipTest) {
+    console.log('[verify] ⚠️ 步骤 1 已跳过——本次不落测试绿凭证（凭证语义 = 测试真跑绿）');
+  } else {
+    const m = [...testStdout.matchAll(/合计: PASS (\d+) \/ FAIL (\d+)/g)].pop();
+    const entry = { ts: new Date().toISOString(), exitCode: 0, suite: 'npm test' };
+    if (m) { entry.passed = Number(m[1]); entry.failed = Number(m[2]); }
+    if (process.env.PIPELINE_RUN_ID) entry.runId = process.env.PIPELINE_RUN_ID;
+    fs.mkdirSync(path.join(ROOT, '.agents'), { recursive: true });
+    fs.appendFileSync(path.join(ROOT, '.agents', 'verifications.jsonl'), `${JSON.stringify(entry)}\n`);
+    console.log(`[verify] 🧾 测试绿凭证已落账 verifications.jsonl${entry.passed !== undefined ? `（PASS ${entry.passed} / FAIL ${entry.failed}）` : ''}`);
+  }
+} catch (e) {
+  console.error(`[verify] ⚠️ 凭证落账失败（${e.code || e.message}）——不阻断，关单门前置将按无凭证告警`);
+}
 console.log('[verify] ✅ 全绿——可以关单（逐条勾验验收标准补证据后 intent/plan → done）');

package/templates/_agents/scripts/verify.test.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // verify.mjs 的 fixture 测试（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具根，不触真实 npm test 与 workflow）
 // 断言：①绿路径（假过 + 空夹具闭环）exit 0；②步骤 1 假败 exit 1 且不出全绿；
-//       ③步骤 2 配对断裂夹具 exit 1（verify 自身标记断言——孙进程 stdio inherit 输出不进本测试管道）。
+// ③步骤 2 配对断裂夹具 exit 1（verify 自身标记断言——孙进程 stdio inherit 输出不进本测试管道）；
+// ④⑤⑥凭证落账三态（绿落 / check-loop 红不落 / 无汇总行省略计数键）；
+// ⑦装户仓（cwd 无 package.json）未给 --test-cmd → 跳过步骤 1、不落凭证、仍跑步骤 2、exit 0。
 // 用法：node templates/_agents/scripts/verify.test.mjs
 import fs from 'node:fs';
 import os from 'node:os';
@@ -46,10 +48,10 @@ const mkBroken = () => {
   ].join('\n'), 'utf8');
   return d;
 };
-// 假命令（绝对路径直调，不依赖 PATH，跨平台无引号问题）
-const mkCmd = (code) => {
+// 假命令（绝对路径直调，不依赖 PATH，跨平台无引号问题）；out 可选输出汇总行
+const mkCmd = (code, out = '') => {
   const f = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'verify-cmd-')), `exit${code}.mjs`);
-  fs.writeFileSync(f, `process.exit(${code});`, 'utf8');
+  fs.writeFileSync(f, `process.stdout.write(${JSON.stringify(out)});process.exit(${code});`, 'utf8');
   return f;
 };
 const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv], { encoding: 'utf8', ...opts });
@@ -81,6 +83,55 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 4：绿路径凭证落账（2026-10-07 verify-evidence）——全绿后 fixture 台账出合法绿行 ----
+{
+  const root = mkfix();
+  const r = run(['--test-cmd', `node ${mkCmd(0, '合计: PASS 3 / FAIL 0\n')}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  const vp = path.join(root, '.agents', 'verifications.jsonl');
+  const line = fs.existsSync(vp) ? JSON.parse(fs.readFileSync(vp, 'utf8').trim()) : null;
+  check('场景 4：全绿 → verifications.jsonl 落绿行（exitCode 0 + 计数捕获）',
+    r.status === 0 && line !== null && line.exitCode === 0 && line.passed === 3 && line.failed === 0
+      && typeof line.ts === 'string' && r.stdout.includes('凭证已落账'),
+    `exit=${r.status} line=${JSON.stringify(line)}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 5：红路径不落账（check-loop 红 → fail-fast 在落账前退出）----
+{
+  const root = mkBroken();
+  const r = run(['--test-cmd', `node ${mkCmd(0)}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  check('场景 5：npm test 绿但 check-loop 红 → 无凭证行（凭证语义 = verify 全绿）',
+    r.status === 1 && !fs.existsSync(path.join(root, '.agents', 'verifications.jsonl')),
+    `exit=${r.status}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 6：输出无汇总行 → 计数键省略（exitCode 才是硬事实）----
+{
+  const root = mkfix();
+  const r = run(['--test-cmd', `node ${mkCmd(0, 'ok\n')}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  const vp = path.join(root, '.agents', 'verifications.jsonl');
+  const line = fs.existsSync(vp) ? JSON.parse(fs.readFileSync(vp, 'utf8').trim()) : null;
+  check('场景 6：无汇总输出 → 绿行落盘但计数键省略',
+    r.status === 0 && line !== null && line.exitCode === 0 && !('passed' in line) && !('failed' in line),
+    `line=${JSON.stringify(line)}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 7：装户仓（cwd 无 package.json）且未给 --test-cmd → 跳过步骤 1、不落凭证、仍跑步骤 2 → exit 0 ----
+{
+ const root = mkfix();
+ const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-'));
+ const r = run([], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: root } });
+ check('场景 7：exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+ check('场景 7：步骤 1 显式跳过（⏭ 1/2）、步骤 2 通过且全绿', r.stdout.includes('⏭ 1/2') && r.stdout.includes('✅ 2/2') && r.stdout.includes('全绿'), r.stdout);
+ check('场景 7：跳过时不落测试绿凭证（防假绿）',
+ !fs.existsSync(path.join(root, '.agents', 'verifications.jsonl')) && r.stdout.includes('不落测试绿凭证'),
+ r.stdout);
+ fs.rmSync(root, { recursive: true, force: true });
+ fs.rmSync(bare, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node templates/_agents/scripts/verify.test.mjs');

package/templates/_agents/skills/verify-ui/SKILL.md

@@ -3,22 +3,59 @@ name: verify-ui
 description: 启动本地服务并用浏览器实测 UI 改动（只读验证、不留脏数据）；项目无测试基建时靠实测兜底。当用户要求"实测 / UI 验证 / 浏览器验证"时使用。
 ---
 
-# verify-ui — UI 实测引导（骨架，项目按实际填「启动命令 / 实测入口」）
+# verify-ui — UI 实测引导
+
+无测试基建时，UI 改动必须浏览器实测。步骤：
 
 ## 1. 起服务
 
-- API：<待填：启动命令（见 .agents/notes/runtime-env.md §2）>
-- 前端：<待填：启动命令>
+启动命令**不写死在本文件**（本文件是 managed 件，随包升级覆盖——项目特定值写这里会丢）：以 `.agents/notes/runtime-env.md`「本地端口与进程」节的记录为准；该节无记录时，先起服务并把命令补记进该文件再继续。
 
 进程清单记进 `.agents/notes/runtime-env.md`，实测结束必须关闭。
 
-## 2. 实测步骤
+## 2. 浏览器验证
+
+- 优先 `browser` 工具；不可用时用 `.agents/scripts/e2e/harness.mjs`（如项目已装；封装 `launch`/`seedSession`/`goto`/`hardGoto`/`clickText`/`pressKey`/`ensureClean`/`screenshot` + 网络/控制台/toast 采集器）；自写脚本优先复用其常量与函数。
+- 浏览器首选**较新的 Chromium 内核 headless**（如 Edge `--headless=new`）——旧版 Chrome 会把 antd 图标字体渲染成方框、表格 `waitFor` 超时（见下「浏览器选择」）。
+- 登录态：先调 API 登录拿 token，注入前端约定的 localStorage 键，**并整页重载**让前端状态库重读 token（仅改 hash 的导航不重建文档，会被路由守卫弹回登录页）。
+- 路由为 hash 模式时：`goto` 用 hash；深链接（query 变化）用 `hardGoto`（about:blank 中转强制新文档）。
+
+## 3. 实测步骤
 
 1. 打开目标页面，按改动点逐项操作：正常路径一条 + 失败路径一条（校验/空态/权限）。
 2. 证据落盘：截图或关键控制台/网络报文，路径写在任务文档「验收标准」勾验项后。
-3. 不留脏数据：验证产生的临时数据当场删除或还原；不确定可回滚的操作先停下问用户。
+3. **不留脏数据**：验证产生的临时数据当场删除或还原；清理**只按本次创建的 ID 精确删除**（ID 取自网络捕获的 POST 响应），**禁止按文案/字段模糊匹配**——模糊匹配会误删用户手建数据；清理脚本一律先备份再删；不确定可回滚的操作先停下问用户。
 
-## 3. 收尾
+## 4. 收尾
 
 - 关闭本次起动的全部进程（按 §1 清单逐个停）。
 - 结论按「页面 / 步骤 / 期望 vs 实际 / 证据」回报；发现缺陷只记录定性，不修代码（修复走 build/maintain 流程）。
+
+## 关键坑
+
+- API 用 **HTTP** 避开自签证书问题（HTTPS 自签证书会让浏览器/脚本报错或需额外信任配置）。
+- MCP 报「browser is already running」是残留实例占 MCP 专用 profile 锁（`~/.cache/chrome-devtools-mcp/`），清掉对应 chrome 进程重试即可，勿误判为 MCP 不可用。
+- 布局类修复用 `getBoundingClientRect` 程序化检测，比截图肉眼更可靠。
+- 后台任务生命周期不可依赖（实测可长可短）：长命服务一律独立进程起（如 PowerShell `Start-Process`）。
+- 用 shell 工具起长命服务时**勿在命令末尾接管道**（`| tail` 等）——子进程继承 stdout 句柄会让命令永不返回，直到被工具超时杀掉（并可能连带杀掉服务）。
+
+### 浏览器选择
+
+- 旧版 Chrome（实测 83）内核太旧 → antd 图标字体全渲染成方框、表格 `waitFor` 超时。**优先较新的 Chromium 内核**（如 Edge `--headless=new`）；harness 的 `CHROME` 常量按本机实际安装路径改。
+
+### antd 交互（JS `.click()` 不够）
+
+- 按钮文本内含空格（`确 定` / `保 存` / `取 消`）→ 匹配须去空白，勿用 `innerText === '确定'`。
+- Select / Picker / Dropdown 的 `.click()` 打不开弹层 → 须 `Input.dispatchMouseEvent`（mousedown+mouseup 序列）；普通按钮用 `clickText` 够用，弹层控件须补 `realClick`。
+- `new KeyboardEvent('Escape')` 关不掉弹层 → 须 `Input.dispatchKeyEvent`（rawKeyDown+keyUp）。
+- **关弹层慎用 Esc**：antd Drawer 同样响应 Esc，会连带关闭抽屉并 reset 表单（表现为「保存后列表无新行」，易误判为保存链路故障）——改点遮罩/关闭按钮。
+- 表格行常无 `tr[data-row-key]` 属性 → 用 `.ant-table-tbody > tr.ant-table-row` + textContent 过滤业务键（如单号）定位行。
+- 宽表 `:scroll="{x:N}"` 截图前把 `.ant-table-content` scrollLeft 置底，露出右侧列。
+- 虚拟滚动下拉（a-select）DOM 只渲染约 10 个节点 → **勿按 DOM 节点数断言选项条数**，按接口响应条数断言。
+
+### CDP 采集（SPA hash 导航不重建文档）
+
+- Log/Console 采集不随导航重置 → 每次导航前重置采集器，防上一页错误泄漏成后续页面的「控制台错误」。
+- toast 观察器须**导航前**安装；导航后装会漏首屏 toast。
+- 首屏无 token 被路由守卫落登录页：写 localStorage 后仅 hash 变化的 `Page.navigate` 不整页重载、前端状态库仍持空 token → 须 `about:blank` 中转强制新文档，或写后 `Page.reload`。
+- 同路由 hash query 变化不重挂载（`#/x?k=A` → `#/x?k=B`）→ 深链接用例走 `about:blank` 中转。