agentic-flow-kit 1.3.0 → 1.5.0

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

@@ -0,0 +1,63 @@
+// pipeline-run-run.mjs — run 存储层（2026-10-08 engine-quality-batch，L2 自 pipeline-run.mjs 拆出）
+// ctxEnv / moduleList / runFileOf / loadRun / saveRun / emit / latestRunId / newRunId + 时间工具（nowIso/today/pad）——
+// run 文件（.agents/cache/pipeline-runs/<id>.json）原子读写与事件流；run schema 零变化。
+// 测试注入契约原样：PIPELINE_RUN_ROOT / PIPELINE_RUN_BIN / PIPELINE_RUN_GIT_BIN（ctxEnv）与
+// PIPELINE_RUN_TODAY（today——时钟依赖消除锚，spec §测试注入契约）。
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const nowIso = () => new Date().toISOString();
+export const today = () => process.env.PIPELINE_RUN_TODAY || nowIso().slice(0, 10);
+export const pad = (n) => String(n).padStart(2, '0');
+
+// ── 环境解析（测试注入点） ─────────────────────────────────────────────
+export function ctxEnv(overrideRoot) {
+  const root = path.resolve(overrideRoot || process.env.PIPELINE_RUN_ROOT || process.cwd());
+  const bin = path.resolve(process.env.PIPELINE_RUN_BIN || path.join(root, '.agents', 'scripts'));
+  const gitPrefix = (process.env.PIPELINE_RUN_GIT_BIN || 'git').split(/\s+/).filter(Boolean);
+  return { root, bin, gitPrefix, runsDir: path.join(root, '.agents', 'cache', 'pipeline-runs') };
+}
+
+export function moduleList(ctx) {
+  try {
+    return fs.readFileSync(path.join(ctx.root, '.agents', 'workflow-modules.txt'), 'utf8')
+      .split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+  } catch { return ['backend', 'frontend', 'ui', 'infra', 'integration', 'pipeline', 'wiki']; } // 夹具缺表时的回退默认（warning 由调用方打）
+}
+
+// ── run 文件（原子写；事件 append-only） ──────────────────────────────
+export function runFileOf(ctx, runId) { return path.join(ctx.runsDir, `${runId}.json`); }
+
+export function loadRun(ctx, runId) {
+  const f = runFileOf(ctx, runId);
+  if (!fs.existsSync(f)) return null;
+  try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; }
+}
+
+export function saveRun(ctx, run) {
+  fs.mkdirSync(ctx.runsDir, { recursive: true });
+  run.updatedAt = nowIso();
+  const f = runFileOf(ctx, run.runId);
+  const tmp = f + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(run, null, 2) + '\n');
+  fs.renameSync(tmp, f);
+}
+
+export function emit(run, ev) { run.events.push({ t: nowIso(), ...ev }); }
+
+export function latestRunId(ctx) {
+  if (!fs.existsSync(ctx.runsDir)) return null;
+  const ids = fs.readdirSync(ctx.runsDir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort();
+  for (let i = ids.length - 1; i >= 0; i--) {
+    const r = loadRun(ctx, ids[i]);
+    if (r && !['done', 'aborted'].includes(r.stopType)) return ids[i];
+  }
+  return ids[ids.length - 1] || null;
+}
+
+export function newRunId(requirement) {
+  const d = new Date();
+  const ascii = (requirement.toLowerCase().match(/[a-z0-9]{2,}/g) || []).slice(0, 3).join('-') || 'task';
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}-${ascii}-${rand}`;
+}

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

@@ -19,9 +19,7 @@
 import fs from 'node:fs';
 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 KINDS = ['require', 'fix', 'verify', 'review', 'deploy'];
 const LEVELS = ['L0', 'L1', 'L2', 'L3'];
 const TERMINAL = ['done', 'superseded', 'cancelled', 'closed'];
@@ -29,61 +27,13 @@ const FIX_CAP = 3;
 const GIT_NEVER_FLAGS = ['--no-verify', '-n']; // 不变量：任何 git 调用不得携带（防御性断言，正常路径不会拼出）
 
 function fail(msg, code = 1) { console.error('❌ ' + msg); process.exit(code); }
-const nowIso = () => new Date().toISOString();
-const today = () => process.env.PIPELINE_RUN_TODAY || nowIso().slice(0, 10);
-const pad = (n) => String(n).padStart(2, '0');
-
-// ── 环境解析（测试注入点） ─────────────────────────────────────────────
-function ctxEnv(overrideRoot) {
-  const root = path.resolve(overrideRoot || process.env.PIPELINE_RUN_ROOT || process.cwd());
-  const bin = path.resolve(process.env.PIPELINE_RUN_BIN || path.join(root, '.agents', 'scripts'));
-  const gitPrefix = (process.env.PIPELINE_RUN_GIT_BIN || 'git').split(/\s+/).filter(Boolean);
-  return { root, bin, gitPrefix, runsDir: path.join(root, '.agents', 'cache', 'pipeline-runs') };
-}
-
-function moduleList(ctx) {
-  try {
-    return fs.readFileSync(path.join(ctx.root, '.agents', 'workflow-modules.txt'), 'utf8')
-      .split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
-  } catch { return ['backend', 'frontend', 'ui', 'infra', 'integration', 'pipeline', 'wiki']; } // 夹具缺表时的回退默认（warning 由调用方打）
-}
 
-// ── run 文件（原子写；事件 append-only） ──────────────────────────────
-function runFileOf(ctx, runId) { return path.join(ctx.runsDir, `${runId}.json`); }
-
-function loadRun(ctx, runId) {
-  const f = runFileOf(ctx, runId);
-  if (!fs.existsSync(f)) return null;
-  try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; }
-}
-
-function saveRun(ctx, run) {
-  fs.mkdirSync(ctx.runsDir, { recursive: true });
-  run.updatedAt = nowIso();
-  const f = runFileOf(ctx, run.runId);
-  const tmp = f + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(run, null, 2) + '\n');
-  fs.renameSync(tmp, f);
-}
 
-function emit(run, ev) { run.events.push({ t: nowIso(), ...ev }); }
-
-function latestRunId(ctx) {
-  if (!fs.existsSync(ctx.runsDir)) return null;
-  const ids = fs.readdirSync(ctx.runsDir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort();
-  for (let i = ids.length - 1; i >= 0; i--) {
-    const r = loadRun(ctx, ids[i]);
-    if (r && !['done', 'aborted'].includes(r.stopType)) return ids[i];
-  }
-  return ids[ids.length - 1] || null;
-}
-
-function newRunId(requirement) {
-  const d = new Date();
-  const ascii = (requirement.toLowerCase().match(/[a-z0-9]{2,}/g) || []).slice(0, 3).join('-') || 'task';
-  const rand = Math.random().toString(36).slice(2, 6);
-  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}-${ascii}-${rand}`;
-}
+import { nowIso, today, ctxEnv, moduleList, loadRun, saveRun, emit, latestRunId, newRunId } from './pipeline-run-run.mjs';
+import { fmGet, placeholdersIn, sectionBody, validateDraftContent, closeoutComplete, summarizeDoc } from './pipeline-run-docs.mjs';
+// 拆分（2026-10-08 engine-quality-batch）：文档纯函数层 / run 存储层迁出本文件（判据注释随函数迁走，
+// 对外导出面经下行 re-export 保持不变——stageBar/parseKV 仍在本文件）；本文件 = CLI 编排层 + 状态机。
+export { placeholdersIn, validateDraftContent, closeoutComplete } from './pipeline-run-docs.mjs';
 
 // ── 门执行（唯一子进程出口；记录真实退出码） ──────────────────────────
 function runNode(ctx, run, script, args) {
@@ -114,78 +64,8 @@ function runGit(ctx, run, args) {
 function readDoc(ctx, rel) {
   try { return fs.readFileSync(path.join(ctx.root, rel), 'utf8'); } catch { return null; }
 }
-function fmGet(text, key) {
-  const m = text.split(/\r?\n/).find((l) => l.startsWith(`${key}:`));
-  return m ? m.slice(key.length + 1).trim() : null;
-}
 function docState(ctx, rel) { const t = readDoc(ctx, rel); return t ? fmGet(t, '状态') : null; }
 
-// 占位符判定（复核 P1-3 收窄，2026-10-02）：先剔除 code span（`…`）与引号串（"…"）——
-// 正文合法的命令语法占位（如 `next --delegated "<原话>"`）几乎总在 code span 内，
-// 模板实占位符（如 <为什么做；写明需求来源…>）从不包 code span；再匹配剩余裸尖括号。
-export function placeholdersIn(text) {
-  const stripped = String(text)
-    .replace(/^```[\s\S]*?^```$/gm, '') // 复核 P2-B：跨行 code fence 整块剔除（围栏内命令示例占位不属模板占位符）
-    .replace(/`[^`\n]*`/g, '')
-    .replace(/"[^"\n]*"/g, '');
-  const hits = [];
-  for (const re of [/<[^>\n]{1,60}>/g, /YYYY-MM-DD 用户/g]) {
-    let m; while ((m = re.exec(stripped))) hits.push(m[0]);
-  }
-  return [...new Set(hits)].slice(0, 5);
-}
-
-function sectionBody(text, title) {
-  const lines = text.split(/\r?\n/);
-  const i = lines.findIndex((l) => l.trim() === `## ${title}` || l.trim() === `## ${title}（L1 微改动无实质内容可删本节，不硬填）` || l.trim().startsWith(`## ${title}`));
-  if (i < 0) return null;
-  const body = [];
-  for (let j = i + 1; j < lines.length; j++) {
-    if (/^##\s/.test(lines[j])) break;
-    body.push(lines[j]);
-  }
-  return body.join('\n').trim();
-}
-
-export function validateDraftContent(text, kind, level) {
-  const problems = [];
-  if (!text) return ['文件不存在或为空'];
-  const state = fmGet(text, '状态');
-  if (!state) problems.push('frontmatter 缺「状态:」行');
-  if (kind !== 'incident' && !fmGet(text, '级别')) problems.push('frontmatter 缺「级别:」行');
-  const ph = placeholdersIn(text);
-  if (ph.length) problems.push(`模板占位符残留：${ph.join('、')}`);
-  const required = {
-    intent: level === 'L1' ? ['背景与问题', '目标', '验收标准'] : ['背景与问题', '历史教训/防复发', '目标', '非目标', '约束', '验收标准'],
-    spec: ['功能行为', '数据流', '系统改动', '约束遵守映射'],
-    plan: level === 'L1' ? ['改动方案', '约束与风险', '验证计划'] : ['改动方案', '任务拆解', '执行顺序', '验证计划'],
-    incident: ['时间线', '根因', '复盘三件套'],
-  }[kind] || [];
-  for (const sec of required) {
-    const b = sectionBody(text, sec);
-    if (b === null) { if (!(level === 'L1' && ['非目标', '约束', '任务拆解', '执行顺序'].includes(sec))) problems.push(`缺节：## ${sec}`); }
-    else if (!b) problems.push(`节为空：## ${sec}`);
-  }
-  return problems;
-}
-
-export function closeoutComplete(text) {
-  const body = sectionBody(text, '验收标准');
-  if (body === null) return { ok: false, problems: ['缺「## 验收标准」节'] };
-  const lines = body.split(/\r?\n/);
-  const open = lines.filter((l) => /^\s*-\s\[\s\]\s/.test(l));
-  // 复核 P2-6：证据冒号后须直接跟内容（非空白、非收括号）——「（证据：）」空值不算过
-  const checkedNoEv = lines.filter((l) => /^\s*-\s\[x\]\s/.test(l) && !/证据[:：][^）\s]/.test(l));
-  const problems = [];
-  if (open.length) problems.push(`未勾验收 ${open.length} 条`);
-  if (checkedNoEv.length) problems.push(`已勾缺证据 ${checkedNoEv.length} 条`);
-  return { ok: problems.length === 0, problems };
-}
-
-function summarizeDoc(text) {
-  const body = text.split(/\r?\n/).filter((l) => l.trim() && !l.startsWith('---') && !/^状态:|^级别:|^日期:|^模块:|^备注:|^risk_level:/.test(l));
-  return body.slice(0, 3).join(' / ').slice(0, 200);
-}
 
 // ── 工单构建 ───────────────────────────────────────────────────────────
 function wo(run, o) {
@@ -211,7 +91,7 @@ function stopConfirm(ctx, run, docRel, points, ledger) {
   printRun(ctx, run);
   process.exit(0);
 }
-function stopGateFail(ctx, run, stage, problems, exitHint) {
+function stopGateFail(ctx, run, stage, problems) {
   run.workOrder = null;
   run.stopType = 'gate-fail';
   run.stage = stage;
@@ -318,11 +198,11 @@ function confirmGate(ctx, run, docRel, quote, to) {
     const tail = (r.stderr || r.stdout).split(/\r?\n/).filter(Boolean).slice(-6).join(' | ');
     return { ok: false, msg: `confirm-doc exit ${r.exit}：${tail}` };
   }
-  emit(run, { type: 'confirm', doc: docRel, to: to || nextConfirmTarget(docState(ctx, docRel), docRel), source: quote ? 'chat-delegated' : 'tty', ...(quote ? { quote } : {}) });
+  emit(run, { type: 'confirm', doc: docRel, to: to || nextConfirmTarget(docState(ctx, docRel)), source: quote ? 'chat-delegated' : 'tty', ...(quote ? { quote } : {}) });
   return { ok: true };
 }
 // 语义上 confirm-doc 自行决定目标态（approved/done/fixed/closed）；事件里记录结果态
-function nextConfirmTarget(curState, docRel) { return curState || 'approved'; }
+function nextConfirmTarget(curState) { return curState || 'approved'; }
 
 // managedFaceCheck（复核 P2-4 修复 A′，2026-10-02 用户拍板）：提交集命中 kit.json 台账面或包源
 // templates/_agents/ 时——包源环境（bin/flow-kit.mjs 可达）自动跑 sync 刷台账并把 kit.json 与 sync

package/templates/_agents/scripts/policy.mjs

@@ -69,6 +69,31 @@ export const POLICIES = {
     riskLevelSince: '2026-10-01',
     verifySince: '2026-10-07', // 测试绿机器凭证生效日（2026-10-07 verify-evidence）；v1-v4 无此键 → 前置与对账整体跳过
   },
+  // 版本 6 = 版本 5 的全部键 + verifyDocSince（测试绿凭证与被证明对象的绑定日，2026-10-08 verify-doc-binding）。
+  // 背景（2026-10-08 verify-doc-binding）：v5 的凭证行只记 {ts, exitCode, suite, passed, failed}，
+  // **没有字段能承载「它是为哪一单落的」**，而两个消费方（confirm-doc 置 done 前置 / 检查 8 对账）
+  // 都只问「全仓任意一份 24h 内绿行」→ 跑一次 verify 就能给全仓任意一单的「测试绿」声明背书，
+  // 这是自证式验证的教科书形态（证据与被证明对象零绑定）。
+  // 本版本只加一个开关键：**缺键（v1-v5）时两个消费方维持 v5 的全局行为逐字不变**（存量装户与存量
+  // fixture 零变化、零新增告警）；本仓升 v6 后才按 doc 精确匹配。抄全键仍是铁律（见 v2 注释）。
+  6: {
+    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',
+    // 凭证按 doc 绑定的生效**时刻**（ISO 8601，含 T/Z）；v1-v5 无此键 → 两个消费方维持 v5 全局行为。
+    // 2026-10-09 verifydoc-anchor：值从日期 '2026-10-08' 升级为时刻——本仓 v6 上线当日（本地 17:37 =
+    // 09:37Z）之前 done 的单（selfmeasure 00:22Z / gate-roi-metrics 03:25Z）在日期粒度下被误纳入精确匹配、
+    // 产 3 条不可消退 advisory（它们关单时 --doc 机制尚不存在，无从补证）；升级为时刻后按 done ts 精确比较，
+    // 机制上线前的存量单退回 v5 全局布尔（不误报、不伪造），与检查 15/18 的生效日锚同构。
+    // 消费方：检查 8 的 verifyDocInWindow（done ts ≥ 本值才启用精确匹配）。
+    verifyDocSince: '2026-10-08T09:37:35Z',
+  },
 };
 
 export function loadKitPolicy(root) {
@@ -90,17 +115,26 @@ export function auditEnabled(policy) {
   return policy.audit !== false;
 }
 
-// ---- 测试绿凭证判定（2026-10-07 verify-evidence）----
+// ---- 测试绿凭证判定（2026-10-07 verify-evidence；2026-10-08 verify-doc-binding 增 doc 绑定）----
 // 单源（confirm-doc done 前置与 check-loop 检查 8 对账共用——防两处窗口字面量漂移，N3 教训）：
-// hasFreshVerifyLine(lines, now)：verifications.jsonl 的行数组里是否存在「ts 距 now ≤ 24h 且
+// hasFreshVerifyLine(lines, now, doc)：verifications.jsonl 的行数组里是否存在「ts 距 now ≤ 24h 且
 // exitCode === 0」的绿行。坏行（非 JSON / 缺 ts）跳过不抛；窗口 24h = 覆盖「跑 verify → 跨会话/
 // 隔夜 → 次日关单」节奏（spec 2026-10-07-verify-evidence 论证）。
-export function hasFreshVerifyLine(lines, now = Date.now()) {
+//
+// doc 绑定（2026-10-08 verify-doc-binding，第三参）：
+//   doc 为空/缺省 → 逻辑与 2026-10-07 版**逐字相同**（全量行扫描）——v1-v5 装户走这条，零变化；
+//   doc 非空     → 额外要求该行 `e.doc === doc`（**精确等值**，不做前缀/子串/形态匹配——
+//                  沿 check8-digit-sha-misfire「文本启发式须可被实证兜底，禁以形态抢先分类」纪律）。
+//   为什么必须精确：放宽成「包含即认」等于给跨单背书开后门，那正是本单要消灭的漏洞。
+//   不带 doc 落账的行（CI 场景）**不给任何单背书**——doc 为 null 时 e.doc === doc 恒假。
+export function hasFreshVerifyLine(lines, now = Date.now(), doc = null) {
+  const byDoc = typeof doc === 'string' && doc !== '';
   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') {
+        if (byDoc && e.doc !== doc) continue;
         const t = Date.parse(e.ts);
         if (Number.isFinite(t) && now - t <= 24 * 60 * 60 * 1000) return true;
       }

package/templates/_agents/scripts/source-sync-check.mjs

@@ -112,12 +112,12 @@ function printDiff(result) {
 
 const isMain = process.argv[1] && process.argv[1].endsWith('source-sync-check.mjs');
 if (isMain) {
-  let jsonMode = false, diffMode = false, gateMode = false;
+  let jsonMode = false, gateMode = false;
   let pkgRoot = null, target = null;
   for (let i = 0; i < process.argv.length - 2; i++) {
     const a = process.argv[2 + i];
     if (a === '--json') jsonMode = true;
-    else if (a === '--diff') diffMode = true;
+    else if (a === '--diff') { /* diff 为默认输出模式，无需置位 */ }
     else if (a === '--gate') gateMode = true;
     else if (a === '--pkg-root') pkgRoot = process.argv[2 + i + 1];
     else if (a === '--target') target = process.argv[2 + i + 1];

package/templates/_agents/scripts/source-sync-check.test.mjs

@@ -125,7 +125,7 @@ if (!SRC_ROOT) {
     drift: r.drift.map((d) => ({ rel: d.rel, pkgSha: d.pkgSha.slice(0, 8), tgtSha: d.tgtSha.slice(0, 8) })),
   }, null, 2);
   let parsed = null;
-  try { parsed = JSON.parse(jsonOut); } catch {}
+  try { parsed = JSON.parse(jsonOut); } catch { /* 非 JSON 输出时 parsed 保持 null，S6 判失败路径 */ }
   check('S6 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.missing));
 }
 

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

@@ -125,7 +125,6 @@ for (const line of fs.readFileSync(path.join(WIKI, 'INDEX.md'), 'utf8').split(/\
 }
 
 const diff = (a, b) => [...a].filter((x) => !b.has(x));
-const eq = (a, b) => a.size === b.size && diff(a, b).length === 0;
 
 // ---- 1. 文件级三方比对 ----
 for (const [label, extra] of [

package/templates/_agents/scripts/verify.mjs

@@ -14,7 +14,13 @@
 // 且**不落测试绿凭证**（凭证语义 = 测试真跑绿，跳过即无凭证，防假绿），并提示用
 // --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 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令）
+// --doc 凭证绑定（2026-10-08 verify-doc-binding）：落账行增 `doc` 字段，写入**相对仓库根的 posix 形态**
+//   （win32 反斜杠 / posix 斜杠 / 绝对路径三种写法经 resolve+relative+分隔符归一后落同一值），使凭证
+//   与被证明的那一单绑定。不带 --doc 时仍落行但**不写该键**——CI（kit-ci.yml）无单次上下文，照常记录
+//   事实；这样的行不给任何单背书（消费方按 doc 精确匹配时 e.doc 为 undefined 恒不命中）。
+// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"] [--doc <本单 workflow 路径>]
+//   （--test-cmd 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令；
+//     --doc 把凭证绑到本单，如 --doc workflow/intents/2026-10-08-x.md）
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -27,6 +33,22 @@ 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, '..', '..');
 
+// --doc 解析（沿 --test-cmd 同款取下一 argv 的写法；缺值报用法错误 exit 1 与 --test-cmd 对称）。
+// 归一基准 = **ROOT**（不是 cwd）——消费方两处都以仓库根为基准（check-loop 检查 8 用
+// path.relative(ROOT, intent)；confirm-doc 的 docRelOf 用 path.resolve(root, doc)）。若这里按 cwd
+// 解析而进程不在仓库根（CI / 钩子 / CHECK_LOOP_ROOT 注入夹具），落下的 doc 会是跨目录长路径，
+// 凭证永远匹配不上——**基准必须三处同源**。
+// 不校验目标文件是否存在：凭证记录的是「跑了什么」而非「被证明对象是否有效」，存在性校验属裁决，
+// 越界（沿本件「只编排不裁决」语义）。
+if (args.includes('--doc') && !args[args.indexOf('--doc') + 1]) {
+  console.error('verify: --doc 缺值——用法 node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"] [--doc <本单 workflow 路径>]');
+  process.exit(1);
+}
+const docArg = args.includes('--doc') ? args[args.indexOf('--doc') + 1] : null;
+const docRel = docArg
+  ? path.relative(ROOT, path.resolve(ROOT, docArg)).split(path.sep).join('/')
+  : null;
+
 // 装户仓判定：默认命令只在**当前目录**有 package.json 时才跑（npm test 亦在该目录执行）。
 // 跳过时后续不落测试绿凭证（见文末落账段）。
 const hasRootPackageJson = fs.existsSync(path.join(process.cwd(), 'package.json'));
@@ -66,9 +88,12 @@ try {
     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;
+    // doc 键：未传 --doc 时**不写该键**（不是写 null）——消费方按 doc 精确匹配，undefined 与 null 都恒不命中，
+    // 但缺键让「本行没有绑定对象」这件事在台账盘面上直接可读。
+    if (docRel) entry.doc = docRel;
     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}）` : ''}`);
+    console.log(`[verify] 🧾 测试绿凭证已落账 verifications.jsonl${entry.passed !== undefined ? `（PASS ${entry.passed} / FAIL ${entry.failed}）` : ''}${docRel ? ` 绑定本单 ${docRel}` : '（未带 --doc：不给任何单背书）'}`);
   }
 } catch (e) {
   console.error(`[verify] ⚠️ 凭证落账失败（${e.code || e.message}）——不阻断，关单门前置将按无凭证告警`);

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

@@ -132,6 +132,59 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
  fs.rmSync(bare, { recursive: true, force: true });
 }
 
+// ---- 场景 8：--doc 凭证绑定（2026-10-08 verify-doc-binding）----
+// ① 带 --doc → 末行含 doc 且为规范化 posix 相对路径；② 不带 → 末行**无 doc 键**（不是 null）；
+// ③ win32 反斜杠 / posix / 绝对路径三种写法落同一值（归一是本单的地基，错一处=凭证永远匹配不上）；
+// ④ 缺值 → exit 1 用法错误；⑤ 跳过步骤 1 时即便带 --doc 仍不落账（防假绿语义不得被 --doc 破坏）。
+{
+  const readLast = (root) => {
+    const p = path.join(root, '.agents', 'verifications.jsonl');
+    if (!fs.existsSync(p)) return null;
+    const lines = fs.readFileSync(p, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.length ? JSON.parse(lines[lines.length - 1]) : null;
+  };
+
+  const rootA = mkfix();
+  const rel = 'workflow/intents/2026-10-08-demo.md';
+  const rA = run(['--test-cmd', `node ${mkCmd(0, '合计: PASS 3 / FAIL 0\n')}`, '--doc', rel],
+    { env: { ...process.env, CHECK_LOOP_ROOT: rootA } });
+  const eA = readLast(rootA);
+  check('场景 8①：带 --doc → 末行含 doc 且为 posix 相对路径',
+    rA.status === 0 && eA && eA.doc === rel && rA.stdout.includes('绑定本单'), `exit=${rA.status} entry=${JSON.stringify(eA)}`);
+
+  const rootB = mkfix();
+  run(['--test-cmd', `node ${mkCmd(0)}`], { env: { ...process.env, CHECK_LOOP_ROOT: rootB } });
+  const eB = readLast(rootB);
+  check('场景 8②：不带 --doc → 仍落行但**无 doc 键**（CI 路径不退化；此行不给任何单背书）',
+    eB && eB.exitCode === 0 && !('doc' in eB) && eB.suite === 'npm test', JSON.stringify(eB));
+
+  // 归一：cwd 设为仓库根时，win32 反斜杠 / posix / 绝对路径三种写法须落同一值
+  const rootC = mkfix();
+  const abs = path.join(rootC, rel);
+  const winStyle = rel.split('/').join(path.sep);
+  run(['--test-cmd', `node ${mkCmd(0)}`, '--doc', winStyle], { cwd: rootC, env: { ...process.env, CHECK_LOOP_ROOT: rootC } });
+  const eC1 = readLast(rootC);
+  run(['--test-cmd', `node ${mkCmd(0)}`, '--doc', abs], { cwd: rootC, env: { ...process.env, CHECK_LOOP_ROOT: rootC } });
+  const eC2 = readLast(rootC);
+  check('场景 8③：反斜杠 / posix / 绝对路径三种写法落同一 doc 值（归一是地基）',
+    eC1 && eC1.doc === rel && eC2 && eC2.doc === rel, `win=${JSON.stringify(eC1 && eC1.doc)} abs=${JSON.stringify(eC2 && eC2.doc)}`);
+
+  const rootD = mkfix();
+  const rD = run(['--test-cmd', `node ${mkCmd(0)}`, '--doc'], { env: { ...process.env, CHECK_LOOP_ROOT: rootD } });
+  check('场景 8④：--doc 缺值 → exit 1 + 用法提示',
+    rD.status === 1 && /--doc 缺值/.test(rD.stderr), `exit=${rD.status} ${rD.stderr}`);
+
+  const rootE = mkfix();
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-doc-'));
+  const rE = run(['--doc', rel], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: rootE } });
+  check('场景 8⑤：步骤 1 跳过时即便带 --doc 仍不落账（防假绿语义不被 --doc 破坏）',
+    rE.status === 0 && !fs.existsSync(path.join(rootE, '.agents', 'verifications.jsonl')) && rE.stdout.includes('不落测试绿凭证'),
+    `exit=${rE.status} ${rE.stdout}`);
+
+  for (const r of [rootA, rootB, rootC, rootD, rootE]) fs.rmSync(r, { 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/scripts/workflow-board-server.test.mjs

@@ -14,7 +14,6 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { parseLoopHardBlocks, parseAcceptance, detectAlerts, parseRunFile, runCard, safeRunPath } from './workflow-board-server.mjs';
 import { computeFingerprint } from './confirm-doc.mjs';
-import { stageBar } from './pipeline-run.mjs';
 
 let pass = 0;
 let fail = 0;

package/templates/_agents/scripts/workflow-enums.test.mjs

@@ -2,7 +2,6 @@
 // 判据：① 真实单源文件解析 + 不变量通过 ② 坏数据（坏行/重复键/重复值/缺键/子集破/重叠）fail-loud
 //       ③ 缺文件 fail-loud ④ sh 消费方同口径（sed 可取到全部 8 键）
 // 用法：node templates/_agents/scripts/workflow-enums.test.mjs（npm test 随跑）
-import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';

package/templates/_agents/scripts-test-exempt.txt

@@ -7,4 +7,7 @@ ensure-board.mjs | 看板启动器（需真实端口/进程环境） | 无（工
 policy.mjs | 库件 | 被 check-loop.test.mjs 直接 import 覆盖
 stage-gates.mjs | 库件 | 被 check-loop.test.mjs 直接 import 覆盖（fill-*/confirm-doc.test 消费其行为）
 verify-wiki-consistency.mjs | wiki 一致性校验工具 | 无（工具豁免，后续批次评估补测）
-wiki-search.mjs | 检索库件 | 无（工具豁免，后续批次评估补测）
+wiki-search.mjs | 检索库件 | 无（工具豁免，后续批次评估补测）
+# 2026-10-08 engine-quality-batch：pipeline-run 三层拆分的库件层——纯函数/存储层由 pipeline-run.test.mjs 全量覆盖（断言零改动全过），单建同名测试属形式主义（plan 偏离留痕 ①）
+pipeline-run-docs.mjs | 库件（文档纯函数层，2026-10-08 engine-quality-batch 拆分） | 由 pipeline-run.test.mjs 全量覆盖（断言零改动 29 组全过）
+pipeline-run-run.mjs | 库件（run 存储层，同上拆分） | 由 pipeline-run.test.mjs 全量覆盖（含 PIPELINE_RUN_* 注入契约场景）