agentic-flow-kit 1.6.0 → 1.7.15

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

@@ -10,6 +10,9 @@
 // 结构缓存（2026-09-23 intent kb-search-structure-cache）：可检索子集预提取进 .agents/cache/kb-index.json，
 //   按 [mtimeMs,size] 逐文件失效，口径指纹变化整份作废；匹配/排序/输出路径不变（三路输出与冷扫逐字节一致）；
 //   缓存任何读写异常静默回退全扫。`--include-generated` 走纯扫（bulk 文件不入缓存）。
+// 检索留痕（2026-10-11 P1-1）：每次实际检索后向 .agents/notes/kb-search-ledger.jsonl 追加一行 JSON
+//   （ts/query/scope/hits/top），KB 沉淀↔检索形成可审计闭环；--no-ledger 显式退出；
+//   写失败仅 console.error 一行 WARN，不改变检索输出与退出码。
 // 测试：node .agents/scripts/kb-search.test.mjs（fixture 回归，须全绿）
 // 模块词表：.agents/workflow-modules.txt（--module 取值校验，单源）
 import fs from 'node:fs';
@@ -33,6 +36,7 @@ const USAGE = `用法: node .agents/scripts/kb-search.mjs [选项] <词1> [词2
   --no-cache                     禁用结构缓存，全量扫（与缓存热路径输出逐字节一致）
   --cache <文件>                 结构缓存文件路径覆盖（默认 .agents/cache/kb-index.json；测试注入用）
   --rebuild                      忽略现有缓存重建后回写
+  --no-ledger                    退出检索留痕：不向 .agents/notes/kb-search-ledger.jsonl 追加本次检索记录
   --help                         打印本说明
 
 退出码：0 正常（含无命中）；1 参数错误（无词 / 未知选项 / 非法枚举值）`;
@@ -49,6 +53,7 @@ let includeGenerated = false;
 let noCache = false;
 let cacheFileOverride = ''; // --cache <文件>（board-kb-p1）：测试注入式缓存路径，不再直跑清真实开发缓存
 let rebuild = false;
+let noLedger = false; // --no-ledger（P1-1）：留痕默认开启（审计要完整），显式退出才跳过写 ledger
 const words = [];
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
@@ -62,6 +67,7 @@ for (let i = 0; i < args.length; i++) {
   else if (a === '--no-cache') noCache = true;
   else if (a === '--cache') cacheFileOverride = args[++i] ?? '';
   else if (a === '--rebuild') rebuild = true;
+  else if (a === '--no-ledger') noLedger = true;
   else if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
   else words.push(a);
 }
@@ -88,6 +94,9 @@ if (moduleFilter && !MODULES.includes(moduleFilter)) {
 // 活跃口径 = 单源 doc.status.active ∪ incident.status.active（与 workflow/INDEX.md 活跃层一致，fixed 归档案默认也可命中）
 const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const WF_SECTIONS = ['背景', '目标', '根因', '复盘三件套', '验收标准', '影响面'];
+// wiki 侧节提取白名单（2026-10-10 A1）：wiki 知识文档的骨架节——长文全文 includes 召回差，
+//   节级提取让命中带节名上下文。放此处（WF_SECTIONS 旁，CFG_FP 之前）供指纹派生。
+const WIKI_SECTIONS = ['标题', '摘要', '背景', '结论', '要点', '规范', '用法', '示例'];
 const WIKI_EXCLUDE = new Set(['INDEX.md', '知识沉淀总览.html']);
 const WIKI_MAX_KB = 180;
 
@@ -149,17 +158,20 @@ const ROOT_NS = `${path.resolve('.')}::`;
 const WIKI_EXTS = includeGenerated ? /\.(md|sql|html|csv|json|txt)$/i : /\.(md|sql|html|txt)$/i;
 
 // 行序列化/复活（缓存 schema 的定义者——board-kb-p1 起纳入 CFG_FP 指纹：schema 演进即整份缓存作废）
-const serializeLines = (lines, kind) => lines.map((x) => (kind === 'wf' ? [x.ln, x.section, x.line] : [x.ln, x.line]));
-const reviveLines = (lines, kind) => lines.map((a) => (kind === 'wf' ? { ln: a[0], section: a[1], line: a[2] } : { ln: a[0], line: a[1] }));
+//   2026-10-10 A1：wiki 行从二元组 [ln, line] 升三元组 [ln, section, line]（节级提取随动）——
+//   两 kind 同构后 serialize/revive 按 kind 取三元组即可，旧缓存由 CFG_FP 指纹整份作废。
+const serializeLines = (lines) => lines.map((x) => [x.ln, x.section, x.line]);
+const reviveLines = (lines) => lines.map((a) => ({ ln: a[0], section: a[1], line: a[2] }));
 
 // linesShapeOk：缓存条目 lines 形状校验（board-kb-p1）——JSON 合法但 schema 坏（lines 非数组 / 元素非数组）
 // 一律视同 miss 走 build 重建（头注释「任何读写异常静默回退」契约恢复；此前直接 .map 抛 TypeError exit 1）
 const linesShapeOk = (lines) => Array.isArray(lines) && (lines.length === 0 || lines.every(Array.isArray));
 
 const CFG_FP = createHash('sha256').update(JSON.stringify({
-  v: 1, WF_SECTIONS, ACTIVE_STATUS, WIKI_MAX_KB, excl: [...WIKI_EXCLUDE],
+  v: 3, // 2026-10-10 B3：wiki 条目也存 meta（来源 frontmatter 血缘显示），schema 演进作废旧缓存
+  WF_SECTIONS, WIKI_SECTIONS, ACTIVE_STATUS, WIKI_MAX_KB, excl: [...WIKI_EXCLUDE],
   exts: WIKI_EXTS.source, // schema 派生（board-kb-p1：手抄摘要曾致扩展面演进不触发指纹失效；RegExp.source 跨 includeGenerated 分支稳定）
-  fns: [parseDoc.toString(), workflowLines.toString(), matchWords.toString(), serializeLines.toString(), reviveLines.toString()],
+  fns: [parseDoc.toString(), workflowLines.toString(), wikiLines.toString(), matchWords.toString(), serializeLines.toString(), reviveLines.toString()],
 })).digest('hex').slice(0, 16);
 const cacheUsable = !noCache && !includeGenerated;
 let cache = null;
@@ -186,13 +198,13 @@ function cachedEntry(relPath, kind, build) {
   const e = cache[key];
   if (e && e.kind === kind && Array.isArray(e.st) && e.st[0] === sig[0] && e.st[1] === sig[1] && linesShapeOk(e.lines)) {
     touched.add(key);
-    return { st: e.st, meta: e.meta, title: e.title, lines: reviveLines(e.lines, kind) };
+    return { st: e.st, meta: e.meta, title: e.title, lines: reviveLines(e.lines) };
   }
   const built = build();
   cache[key] = {
     st: sig, kind,
-    ...(kind === 'wf' ? { meta: built.meta, title: built.title } : {}),
-    lines: serializeLines(built.lines, kind),
+    ...(built.meta ? { meta: built.meta, ...(built.title ? { title: built.title } : {}) } : {}),
+    lines: serializeLines(built.lines),
   };
   touched.add(key);
   return { st: sig, meta: built.meta, title: built.title, lines: built.lines };
@@ -249,7 +261,36 @@ function searchWorkflow(words) {
   return results.sort((a, b) => b.score - a.score);
 }
 
-// ---- wiki 检索（口径同 2026-09-21 降噪版 wiki-search）----
+// ---- wiki 检索（口径同 2026-09-21 降噪版 wiki-search；2026-10-10 A1：节级提取 + 主题路径加权）----
+// wiki 侧与 workflow 侧同款行结构（ln + section + line），节提取用 wiki 自己的标题滚动：
+//   wiki 知识文档多为长文，全文 includes 召回差、命中行缺乏上下文——节级提取让命中带节名
+//   （`[<节名>] L<行>: <摘录>`，与 workflow 侧输出对齐）。frontmatter（如有）单列 '(frontmatter)' 节。
+//   提取节白名单 WIKI_SECTIONS（常量定义在文件头部 WF_SECTIONS 旁），与 WF_SECTIONS 平行。
+function wikiLines(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let i = 0;
+  if (/^---\s*$/.test(lines[0] || '')) {
+    out.push({ ln: 1, section: '(frontmatter)', line: lines[0] });
+    for (i = 1; i < lines.length; i++) {
+      out.push({ ln: i + 1, section: '(frontmatter)', line: lines[i] });
+      if (/^---\s*$/.test(lines[i])) { i++; break; }
+    }
+  }
+  let section = '';
+  // wiki 短文常无小节标题（如「# 说明\n正文」）——节白名单只覆盖骨架节，纯标题文档会零命中。
+  //   兜底：全文无任何 `## ` 时正文全收（section 记 '(正文)'）；有 ## 后回到白名单口径。
+  const sawH2 = lines.slice(i).some((l) => /^## /.test(l));
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const h1 = line.match(/^# (.+?)\s*$/);
+    if (h1 && !/^## /.test(line)) { out.push({ ln: i + 1, section: '(标题)', line }); section = ''; continue; }
+    const h2 = line.match(/^## (.+?)\s*$/);
+    if (h2) section = h2[1];
+    if (!sawH2 || WIKI_SECTIONS.some((s) => section.startsWith(s))) out.push({ ln: i + 1, section: section || '(正文)', line });
+  }
+  return out;
+}
 const walkWiki = (dir, rel) => {
   const out = [];
   for (const e of fs.readdirSync(dir)) {
@@ -275,13 +316,21 @@ function searchWiki(words) {
       const e = cachedEntry(p, 'wiki', () => {
         let text;
         try { text = fs.readFileSync(p, 'utf8'); } catch { return { lines: [] }; }
-        return { lines: text.split('\n').map((line, i) => ({ ln: i + 1, line })) };
+        const { meta } = parseDoc(text);
+        return { meta, lines: wikiLines(text) };
       });
       if (!e.lines.length) continue;
       const hits = matchWords(e.lines.filter((x) => words.some((w) => x.line.includes(w))), words);
       if (!hits) continue;
       const kb = size / 1024;
-      results.push({ file: key, total: hits.total, shown: hits.shown, kb, score: hits.total / Math.sqrt(Math.max(kb, 0.1)) });
+      // 主题路径加权（A1）：查询词出现在主题目录名（key 首段，如「项目规范」）时 ×1.2——
+      //   主题归属是 wiki 最有价值的结构特征，纯全文打分完全没用上；权重温和（不压倒命中数主序）
+      const topicHit = words.some((w) => key.includes(w));
+      const score = (hits.total / Math.sqrt(Math.max(kb, 0.1))) * (topicHit ? 1.2 : 1);
+      // 来源血缘（B3，2026-10-10）：wiki frontmatter「来源: workflow/<类型>/<文件>」指回 workflow 归档——
+      //   与 intent/incident 的正向「沉淀:」字段对称。有则结果行显示，无则空（老 wiki 文件零行为变化）
+      const source = (e.meta && e.meta['来源']) || '';
+      results.push({ file: key, total: hits.total, shown: hits.shown, kb, score, source });
     }
   }
   return { results: results.sort((a, b) => b.score - a.score), skipped };
@@ -290,11 +339,13 @@ function searchWiki(words) {
 // ---- 输出 ----
 const top = (arr) => (limit ? arr.slice(0, limit) : arr);
 let anyHits = 0;
+let topFile = null; // 首个展示文件（留痕用）：按展示顺序 workflow→wiki 取 shown[0]，无命中保持 null
 
 if (scope === 'workflow' || scope === 'all') {
   const res = searchWorkflow(words);
   anyHits += res.length;
   const shown = top(res);
+  if (shown.length && !topFile) topFile = `workflow/${shown[0].file}`;
   console.log(`── workflow（${res.length} 个文件命中${res.length > shown.length ? `，展示前 ${shown.length}` : ''}）──`);
   for (const r of shown) {
     console.log(`📄 workflow/${r.file} — ${r.status || '未填状态'} · ${r.level} · ${r.module} · ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB`);
@@ -307,10 +358,11 @@ if (scope === 'wiki' || scope === 'all') {
   const { results: res, skipped } = searchWiki(words);
   anyHits += res.length;
   const shown = top(res);
+  if (shown.length && !topFile) topFile = `wiki/${shown[0].file}`;
   console.log(`── wiki（${res.length} 个文件命中${res.length > shown.length ? `，展示前 ${shown.length}` : ''}）──`);
   for (const r of shown) {
-    console.log(`📄 wiki/${r.file} — ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB`);
-    for (const h of r.shown) console.log(`   L${h.ln}: ${h.line.trim().slice(0, 130)}`);
+    console.log(`📄 wiki/${r.file} — ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB${r.source ? ` · 来源 ${r.source}` : ''}`);
+    for (const h of r.shown) console.log(`   [${h.section || '(无节)'}] L${h.ln}: ${h.line.trim().slice(0, 130)}`);
   }
   if (!res.length) console.log('（无命中）');
   if (skipped) console.log(`（wiki 跳过 ${skipped} 个产物/大文件——--include-generated 纳入）`);
@@ -321,3 +373,26 @@ console.log(`\n${anyHits ? `合计 ${anyHits} 个文件命中（${words.join(' A
   (scope === 'all' ? '；`--scope` 限定语料、`--status all` 显式全量' : ''));
 
 saveCache();
+
+// ---- 检索留痕（P1-1）：append-only 一行 JSON，KB 沉淀↔检索可审计闭环 ----
+// ROOT 与 workflow/、wiki/ 索引根一致（脚本按 cwd 相对路径读语料，ROOT_NS 同源）；
+// 写失败只 WARN 不阻断：留痕是旁路记录，异常必须可见，但绝不能改变检索结果与退出码。
+const LEDGER_FILE = path.join('.agents', 'notes', 'kb-search-ledger.jsonl');
+function appendLedger() {
+  if (noLedger) return;
+  const pad = (n) => String(n).padStart(2, '0');
+  const d = new Date();
+  try {
+    fs.mkdirSync(path.dirname(LEDGER_FILE), { recursive: true });
+    fs.appendFileSync(LEDGER_FILE, `${JSON.stringify({
+      ts: `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`, // ISO 8601 本地时间
+      query: words.join(' '),
+      scope,
+      hits: anyHits, // 切 top 之前的命中总量（workflow + wiki）
+      top: topFile,
+    })}\n`, 'utf8');
+  } catch (e) {
+    console.error(`WARN 检索留痕写入失败（不影响检索结果）：${e && e.message ? e.message : e}`);
+  }
+}
+appendLedger();

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

@@ -175,6 +175,89 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 10：A1 wiki 侧节级提取 + 主题路径加权（2026-10-10）----
+//    wiki 命中带节名（骨架节或无小节兜底）；主题目录命中查询词时排序提前；长文节外内容不参与检索
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-a1-'));
+  fs.mkdirSync(path.join(root, 'wiki', '项目规范'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'wiki', '杂项'), { recursive: true });
+  // 长文：命中在白名单节内（## 结论）+ 节外（## 历史流水，不应被索引）
+  fs.writeFileSync(path.join(root, 'wiki', '项目规范', '权限收敛.md'),
+    '# 权限收敛方案\n\n## 结论\n- 权限收敛后只读接口不再放行写操作。\n\n## 历史流水\n- 2026-09 某次发布也提到权限收敛但属节外内容\n', 'utf8');
+  // 短文：无任何 ## —— 正文兜底全收
+  fs.writeFileSync(path.join(root, 'wiki', '杂项', '说明.md'), '# 说明\n\n权限收敛的领域知识条目。\n', 'utf8');
+  const r = run(root, ['--scope', 'wiki', '--cache', rootCache(root), '权限收敛']);
+  check('场景 10a wiki 长文命中带节名（结论节）',
+    r.status === 0 && /wiki\/项目规范\/权限收敛.md/.test(r.stdout) && /\[结论\]/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  check('场景 10b wiki 长文节外内容不参与检索（历史流水行不进命中摘录）',
+    !/历史流水/.test(r.stdout), r.stdout);
+  check('场景 10c wiki 短文无小节兜底（正文命中，节名 (正文)）',
+    /wiki\/杂项\/说明.md/.test(r.stdout) && /\(正文\)/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  // 主题加权：两文件命中数同量级时，主题名含查询词的「项目规范」排前
+  const order = (r.stdout.match(/^📄 (wiki\/\S+)/gm) || []).map((l) => l.replace('📄 ', ''));
+  check('场景 10d 主题路径加权：主题名命中查询词的文件排前',
+    order.length === 2 && order[0].includes('项目规范'), `order=${JSON.stringify(order)}\n${r.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 11：B3 来源血缘显示（2026-10-10）----
+//    wiki frontmatter「来源: workflow/<类型>/<文件>」→ 结果行带「· 来源 …」；无来源老文件零变化
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-b3-'));
+  fs.mkdirSync(path.join(root, 'wiki', '项目规范'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'workflow', 'intents'), { recursive: true });
+  // 带来源的 wiki 文件（B2 生成的草稿/人工沉淀都是这个形态）
+  fs.writeFileSync(path.join(root, 'wiki', '项目规范', '权限收敛.md'),
+    '---\n来源: workflow/intents/2026-09-12-perm-shrink.md\n---\n# 权限收敛方案\n\n## 结论\n- 权限收敛后只读接口不再放行写操作。\n', 'utf8');
+  // 无 frontmatter 的老 wiki 文件（零行为变化对照）
+  fs.writeFileSync(path.join(root, 'wiki', '项目规范', '老规范.md'), '# 老规范\n\n权限收敛的旧条目。\n', 'utf8');
+  const r = run(root, ['--scope', 'wiki', '--cache', rootCache(root), '权限收敛']);
+  check('场景 11a 有来源的 wiki 结果行显示来源血缘',
+    r.status === 0 && /来源 workflow\/intents\/2026-09-12-perm-shrink\.md/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  check('场景 11b 无 frontmatter 老文件正常命中且无来源行干扰',
+    r.status === 0 && /wiki\/项目规范\/老规范\.md/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  // 来源字段本身可被检索（frontmatter 已进可检索面——双向找链：从 wiki 侧反查 workflow 来源）
+  const r2 = run(root, ['--scope', 'wiki', '--cache', rootCache(root), 'perm-shrink']);
+  check('场景 11c 来源路径本身参与检索（frontmatter 命中）',
+    r2.status === 0 && /wiki\/项目规范\/权限收敛\.md/.test(r2.stdout), `exit=${r2.status}\n${r2.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 12：检索留痕（P1-1）——每次检索后 ledger 追加一行 / --no-ledger 退出 / notes 目录自动创建 ----
+//    ledger 落在 <临时根>/.agents/notes/kb-search-ledger.jsonl（与 workflow/、wiki/ 索引根同 ROOT）
+{
+  const ledgerOf = (root) => path.join(root, '.agents', 'notes', 'kb-search-ledger.jsonl');
+  const ledgerLines = (root) => fs.readFileSync(ledgerOf(root), 'utf8').split('\n').filter(Boolean);
+  const root = mkfix();
+  check('场景 12 前置：.agents/notes 尚不存在', !fs.existsSync(path.join(root, '.agents')));
+  // a) 首次检索 → 恰 1 行、JSON 合法、字段齐全、hits 为数字
+  const r1 = run(root, ['--scope', 'workflow', '编码模板', '冲突']);
+  const lines1 = ledgerLines(root);
+  check('场景 12a 检索后 ledger 存在且恰 1 行', r1.status === 0 && lines1.length === 1, `exit=${r1.status}\n${r1.stderr}`);
+  const entry = JSON.parse(lines1[0]);
+  check('场景 12a ledger 行字段齐全（ts/query/scope/hits/top）',
+    typeof entry.ts === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(entry.ts)
+    && entry.query === '编码模板 冲突' && entry.scope === 'workflow'
+    && entry.hits === 2 && entry.top === 'workflow/intents/2026-09-21-bbb.md', lines1[0]);
+  // b) 已有 ledger 再跑 → 追加成 2 行且旧行原样
+  const r2 = run(root, ['--scope', 'wiki', '编码模板']);
+  const lines2 = ledgerLines(root);
+  check('场景 12b 再次检索追加成 2 行且旧行原样',
+    r2.status === 0 && lines2.length === 2 && lines2[0] === lines1[0]
+    && JSON.parse(lines2[1]).scope === 'wiki' && JSON.parse(lines2[1]).top === 'wiki/测试主题/说明.md', lines2.join('\n'));
+  // c) --no-ledger → 不追加（仍 2 行）
+  const r3 = run(root, ['--no-ledger', '--scope', 'workflow', '编码模板']);
+  check('场景 12c --no-ledger 不追加不新建', r3.status === 0 && ledgerLines(root).length === 2, r3.stderr);
+  // d) 无命中检索也留痕（top=null、hits=0）
+  const r4 = run(root, ['--scope', 'workflow', 'zzz-绝不存在-zzz']);
+  const lines4 = ledgerLines(root);
+  const entry4 = JSON.parse(lines4[2]);
+  check('场景 12d 无命中留痕 top=null 且 hits=0',
+    r4.status === 0 && entry4.query === 'zzz-绝不存在-zzz' && entry4.hits === 0 && entry4.top === null, lines4.join('\n'));
+  check('场景 12e .agents/notes 目录由检索自动创建', fs.statSync(path.join(root, '.agents', 'notes')).isDirectory());
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// pipeline-run — 跨宿主全自动闭环执行器（2026-10-02 pipeline-run；spec workflow/specs/2026-10-02-pipeline-run.md）
+// pipeline-run — 跨宿主全自动闭环执行器（2026-10-02 pipeline-run 立法）
 // 用途：把六阶段闭环的确定性部分代码化为状态机——start/next/status/watch/abort 五子命令；
 //       AI 槽位经工单协议交宿主执行，人件门到点即停、next --delegated "<原话>" 逐份过 confirm-doc。
 // 红线：绝不 spawn AI 会话 / 零依赖 / git 永不 --no-verify / 永不伪造原话 / 永不直改文档状态（唯一入口 confirm-doc）。

package/templates/_agents/scripts/policy.mjs

@@ -95,6 +95,30 @@ export const POLICIES = {
     // 消费方：检查 8 的 verifyDocInWindow（done ts ≥ 本值才启用精确匹配）。
     verifyDocSince: '2026-10-08T09:37:35Z',
   },
+  // 版本 7 = 版本 6 的全部键 + scopeSince（台账「机器派生改动面」的生效时刻，2026-10-09 审查 A1 干净版）。
+  // 背景：委托代录的授权凭据是 `--delegated` 的**用户原话**——机器无法校验自由文本，AI 可无成本复用同一句
+  // （本仓实测「可以」133 次、「确认」60 次），且台账 406 行里仅 6 行为 tty。整条授权链的源头不可核对，
+  // 下游的哈希链/指纹对账/内容绑定全建得很好却是建在空地基上。
+  // 干净版解法：**改动面改由机器派生，AI 无输入面**——confirm-doc 落账时自动记
+  // `scope:{files:[…], sha256}`（被确认文档 + `git status --porcelain` 实测的未提交改动集，归一去重排序后
+  // 取 sha256）。AI 无法伪造这个字段，因为它根本不参与输入；事后对质问的是「这 N 个文件」，而不是一句可复用的原话。
+  // 本版本只加一个开关键：**缺键（v1-v6）时该子检查整体跳过**，存量 406 行零新增告警；抄全键仍是铁律。
+  7: {
+    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',
+    verifyDocSince: '2026-10-08T09:37:35Z',
+    // 生效「时刻」（ISO 8601，UTC）而非日期：本日 04:29Z 已有一批旧口径台账行写入，日期粒度会把它们
+    // 纳入受审范围产出不可消退告警——沿 v6 verifyDocSince 升级为时刻的同款教训。
+    // 消费方：check-loop 检查 15 的 scope 子项（台账行 ts ≥ 本值才判）。
+    scopeSince: '2026-10-09T11:24:43Z',
+  },
 };
 
 export function loadKitPolicy(root) {
@@ -155,3 +179,28 @@ export function hasFreshVerifyLine(lines, now = Date.now(), doc = null) {
 export function ledgerChainHash(row, prevHash) {
   return createHash('sha256').update((prevHash || '') + JSON.stringify(row)).digest('hex');
 }
+
+// ---- 台账 scope（机器派生改动面，2026-10-09 审查 A1 干净版）----
+// scopeDigest(files) = {files, sha256}：files 归一（反斜杠→posix）、去重、排序；sha256 = files.join('\n') 的摘要。
+// **单源**（confirm-doc 落账侧构造与 check-loop 检查 15 校验侧重算共用——防两处归一/排序口径漂移，
+//   N3 教训同款）：任一侧改了口径而另一侧没改，台账会整体判失效。
+// 边界（诚实声明）：scope 是**机器实测**的「确认时刻工作树处于改动态的文件集合」，不是「本次任务应改什么」
+// 的语义判定——它能证明「你放行时盘面上就是这些文件在动」，不能证明「这些改动就是你要的」。
+// 语义正确性仍由指纹（文档内容）+ commit diff（事后对质）承担。
+export function scopeDigest(files) {
+  const norm = [...new Set((Array.isArray(files) ? files : [])
+    .map((f) => String(f).replace(/\\/g, '/').replace(/^\.\//, ''))
+    .filter(Boolean))]
+    .sort();
+  return { files: norm, sha256: createHash('sha256').update(norm.join('\n'), 'utf8').digest('hex') };
+}
+
+// scopeMatches(row)：台账行自带的 scope 是否与按其 files 重算的结果逐字一致。
+// 用于检出「行里改了 files 却没同步 sha256」的手改形态（哈希链能兜住就地改，但整文件重写可重建链——
+//   同一信任边界内的第二道，见 ledgerChainHash 边界声明）。
+export function scopeMatches(row) {
+  if (!row || typeof row !== 'object' || !row.scope) return false;
+  const s = row.scope;
+  if (!Array.isArray(s.files) || typeof s.sha256 !== 'string') return false;
+  return scopeDigest(s.files).sha256 === s.sha256;
+}

package/templates/_agents/scripts/solidify-task.mjs

@@ -7,7 +7,7 @@
 //       # 迁移后，以调用方显式传入的用户原话逐份 confirm-doc --delegated（quote 原样转发）
 //   node .agents/scripts/solidify-task.mjs --topic <主题> --auto
 //       # 迁移后，逐份 confirm-doc --auto（trust-mode=Trusted 才放行；Strict 下被拒并计数失败）
-// 确认门契约（incidents/2026-10-01-v09-review-defects）：--delegated 的 quote 必须来自用户在对话内的
+// 确认门契约（2026-10-01 v09 复盘立法）：--delegated 的 quote 必须来自用户在对话内的
 //   明确原话，由调用方显式传入——本脚本永不编造用户话术。无确认来源时只迁移不落账，末尾打印指引。
 import fs from 'node:fs';
 import path from 'node:path';

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

@@ -102,15 +102,20 @@ function mkFixture() {
 }
 
 // ---- 场景 5：实际仓库扫描 baseline（包源 ≥ 30 份 / 装副本 ≥ 30 份；装户环境无包源 → SKIP）----
+// 纯包源仓（装户端内容清理后）无 `.agents/` 装副本——包源侧仍扫得到，装副本侧 SKIP 不算失败。
 if (!SRC_ROOT) {
   check('S5 baseline SKIP（未探测到包源 templates/_agents——装户环境直跑，不算失败）', true);
 } else {
   const r = sourceSyncCheck({ pkgRoot: SRC_ROOT, target: SRC_ROOT });
   check('S5 实际仓库 包源 ≥ 30 份', r.pkgCount >= 30, '实际 ' + r.pkgCount);
-  check('S5 实际仓库 装副本 ≥ 30 份', r.tgtCount >= 30, '实际 ' + r.tgtCount);
-  // 装副本 kit.json / settings.json 不应在孤儿
-  check('S5 实际仓库 装副本独有（kit.json / settings.json）排除',
-    !r.orphan.some((o) => o.rel === 'kit.json' || o.rel === 'settings.json'));
+  if (!fs.existsSync(path.join(SRC_ROOT, '.agents'))) {
+    check('S5 装副本 SKIP（纯包源仓无 .agents/——装户端内容清理后形态，不算失败）', true);
+  } else {
+    check('S5 实际仓库 装副本 ≥ 30 份', r.tgtCount >= 30, '实际 ' + r.tgtCount);
+    // 装副本 kit.json / settings.json 不应在孤儿
+    check('S5 实际仓库 装副本独有（kit.json / settings.json）排除',
+      !r.orphan.some((o) => o.rel === 'kit.json' || o.rel === 'settings.json'));
+  }
 }
 
 // ---- 场景 6：--json 输出可解析（CLI 子流程）----

package/templates/_agents/scripts/stage-gates.mjs

@@ -204,7 +204,54 @@ export function draftGateFor(kind, root, base) {
   return { ok: true, entry };
 }
 
+// ---- 待澄清标记（2026-10-12 needs-clarification，spec-kit NEEDS CLARIFICATION 对应物）----
+// 动机：本项目的歧义处理此前只有一种形态——**停下来问**（确认门停机）。那是「事后阻塞」：AI 停住等
+//   人，而人在上下文里未必答得上（他刚提的需求，细节是你算出来的）。spec-kit 的做法是**起草期把
+//   歧义显式写下来**（`[NEEDS CLARIFICATION]`），不阻塞起草但禁臆测——「我不知道」是负责，「猜一个」
+//   是失职。本件补这个表达：**零阻塞 + 不许糊过去**。
+// 形态：正文行 `- 待澄清：<问题>`（行首可选列表符；半角冒号兼容）。行首 `- 已澄清：<问题>` **不算**
+//   （同一行改前缀即声明解决，不删行——保留「曾经不清楚过」的痕迹，供事后对质）。
+// ⚠️ 与检查 2（模板占位符）刻意区分：占位符 = 「忘了填」（失职），本标记 = 「这里我不知道」
+//   （负责）。两者都要求作者动作，但语义相反，故不复用同一正则——复用即把负责判成失职。
+// 边界（诚实声明）：**起草门不阻断**（这才是零阻塞的意义），仅在 draft→approved 确认门点名——
+//   确认即「我认可这份文档」，文档里还挂着未澄清项则确认本身失去含义，故此处拒绝落账。
+//   例外：<日期>/YYYY-MM-DD 等占位由检查 2 管，本件不重复拦。
+const CLARIFY_RE = /^\s*[-*]\s*(待澄清|需澄清|待确认细节)\s*[：:]\s*(\S.*)$/;
+
+// openClarifications：抽出正文里未澄清的行（pure，供直测）。返回 [{ lineNo, text }]
+// HTML 注释行不计入——模板自带说明写在注释里，不该被判成作者留下的未澄清项。
+export function openClarifications(body) {
+  const out = [];
+  const lines = String(body || '').replace(/\r\n/g, '\n').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^\s*<!--/.test(l) || /-->\s*$/.test(l)) continue; // 整行注释
+    const m = l.match(CLARIFY_RE);
+    if (m) out.push({ lineNo: i + 1, text: m[2].trim(), kind: m[1] });
+  }
+  return out;
+}
+
+// clarifyGateFor：确认门「待澄清项已解决」前置判（confirm-doc draft→approved 用）
+// 返回 { ok, items?, reason?, hint? }。ok=false 时 items 供逐条点名（不只说「有未澄清项」——
+//   说清是哪几行哪几句，作者才不用回去逐行找）。
+export function clarifyGateFor(abs) {
+  let body = '';
+  try { body = fs.readFileSync(abs, 'utf8'); } catch { return { ok: true, skipped: 'unreadable' }; }
+  const items = openClarifications(body);
+  if (!items.length) return { ok: true, items };
+  const list = items.map((i) => `第${i.lineNo}行「${i.text}」`).join('；');
+  return {
+    ok: false,
+    items,
+    reason: `文档含 ${items.length} 处未澄清项——${list}`,
+    hint: '逐条解决后把行首「待澄清」改为「已澄清」（保留行，便于事后对质曾不清楚过），或直接删行；确认门不接受挂着未澄清项的文档',
+  };
+}
+
 // confirmGateFor：确认门总判（confirm-doc 用；docRel = workflow/specs/... 或 workflow/plans/...）
+// ⚠️ 只判**前置深度**（入口/spec 是否已确认）。待澄清项判定是**同一确认门上的另一条独立判据**，
+//   由 clarifyGateFor 单独承担——两者不合并：合并后拒绝原因会指向「前置」，作者找错地方。
 export function confirmGateFor(root, docRel) {
   const base = path.basename(docRel).replace(/\.md$/, '');
   const kind = docRel.startsWith('workflow/specs/') ? 'spec' : 'plan';
@@ -276,4 +323,4 @@ export function resolveWorkspace(outputPath, rootOverride) {
   return null;
 }
 
-export default { entryConfirmed, specConfirmed, draftGateFor, confirmGateFor, doneGateFor, gitReady, approvedTraceHit, resolveWorkspace, readFm, readLedger };
+export default { entryConfirmed, specConfirmed, draftGateFor, confirmGateFor, clarifyGateFor, openClarifications, doneGateFor, gitReady, approvedTraceHit, resolveWorkspace, readFm, readLedger };

package/templates/_agents/scripts/stage-gates.test.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// stage-gates.test.mjs — 逐阶段前置门 + 待澄清门的纯函数直测（2026-10-12 needs-clarification）
+// 为什么单建本套件（stage-gates.mjs 此前登记 scripts-test-exempt，靠 check-loop.test 间接覆盖）：
+//   本批给该模块加了两条**此前不存在的判据族**（clarifyGateFor / openClarifications），
+//   而这两条**没有 check-loop 侧的对应检查**——check-loop 不消费它们。间接覆盖天然盖不到
+//   「确认门拒绝未澄清项」这条行为，纯函数直测是唯一能钉住它的位置（check 20 的豁免登记
+//   在此更新为「同名直测 + 间接覆盖并有」）。
+// 覆盖：CLARIFY_RE 形态矩阵（正例 5 / 负例 7）+ HTML 注释不计 + 已澄清前缀不计
+//       + clarifyGateFor 三态（无 / 有 / 不可读）+ 行号点名。
+// 用法：node templates/_agents/scripts/stage-gates.test.mjs（npm test 随跑）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { openClarifications, clarifyGateFor } from './stage-gates.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+// ---- T1 正例形态矩阵（5 个写法都应抽出，行号正确）----
+{
+  const body = [
+    '# S',                          // 1
+    '',                             // 2
+    '- 待澄清：错误率判据？',        // 3  ← 行首列表符 + 全角冒号
+    '* 需澄清: 依赖版本未定',        // 4  ← 星号 + 半角冒号 + 同义前缀
+    '  - 待确认细节：用户没说要不要兼容旧数据', // 5 ← 前导空格 + 第三同义前缀
+    '正文里提到「待澄清」二字不算（不是行首列表条目）', // 6 ← 负例
+    '',                             // 7
+    '- 待澄清了：已解决的说法不该被抽', // 8 ← 负例（词后跟了别的字符）
+    '待澄清：无列表符的行不算',       // 9 ← 负例
+    '- 已澄清：这是已解决的',         // 10 ← 负例（前缀已澄清）
+  ].join('\n');
+  const items = openClarifications(body);
+  check('T1 三个同义前缀 + 列表符变体 + 全/半角冒号全命中（5 个写法）', items.length === 3, JSON.stringify(items));
+  check('T1 行号正确（3 / 4 / 5）',
+    items.map((i) => i.lineNo).join(',') === '3,4,5', JSON.stringify(items.map((i) => i.lineNo)));
+  check('T1 抽出的是标记后的正文（不含前缀与冒号）',
+    items[0].text === '错误率判据？' && items[1].text === '依赖版本未定' && items[2].text === '用户没说要不要兼容旧数据',
+    JSON.stringify(items.map((i) => i.text)));
+  check('T1 负例四类全不误抽（正文提及 / 前缀粘连 / 无列表符 / 已澄清）',
+    !items.some((i) => /待澄清了|无列表符|已解决/.test(i.text)), JSON.stringify(items));
+}
+
+// ---- T2 HTML 注释行不计（模板自带说明写在注释里，不该被判成作者的未澄清项）----
+{
+  const body = [
+    '# S',
+    '<!-- 起草时照实写一行 - 待澄清：<你卡在哪>，不要猜 -->',  // 整行注释
+    '- 待澄清：真问题',
+    '<!-- - 待澄清：注释里的第二处 -->',                      // 整行注释
+    '行尾注释不算：- 待澄清：真的吗 <!-- 附注 -->',            // 行尾注释
+  ].join('\n');
+  const items = openClarifications(body);
+  check('T2 整行 HTML 注释里的标记不计（只 1 处命中）', items.length === 1 && items[0].lineNo === 3, JSON.stringify(items));
+  check('T2 行尾注释形态不计（模板说明常这么写）', !items.some((i) => /真的吗/.test(i.text)), JSON.stringify(items));
+}
+
+// ---- T2b 已知边界（跨行 HTML 注释块）——如实钉住，不假装覆盖 ----
+// 逐行过滤只认「整行注释」与「行尾注释」；跨行注释块 <!--\n - 待澄清：x\n--> 的中间行会被抽出。
+// 为何不修：跨行注释在 workflow 文档里零先例（模板说明一律单行注释），为不存在的形态加状态机
+// 是过度工程。**方向是保守的**（多抽一处 → 确认门拒一次，作者看到就改），不会漏放。
+{
+  const items = openClarifications('<!--\n- 待澄清：跨行注释块中间行\n-->');
+  check('T2b 已知边界：跨行注释块中间行会被抽出（保守方向——多拒不漏放）',
+    items.length === 1 && items[0].lineNo === 2, JSON.stringify(items));
+}
+
+// ---- T3 CRLF 与空输入 ----
+{
+  check('T3 CRLF 归一后形态不变（行号按 \\n 计）',
+    openClarifications('- a\r\n\r\n- 待澄清：x\r\n').length === 1);
+  check('T3 空 / undefined 输入 → 空数组（不抛）',
+    openClarifications('').length === 0 && openClarifications(undefined).length === 0 && openClarifications(null).length === 0);
+}
+
+// ---- T4 clarifyGateFor 三态 ----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'stage-gates-test-'));
+  const p = path.join(tmp, 'doc.md');
+  fs.writeFileSync(p, '---\n状态: draft\n---\n# S\n- 待澄清：甲\n- 待澄清：乙\n');
+  const g = clarifyGateFor(p);
+  check('T4 挂未澄清项 → ok=false 且 items 含两处', !g.ok && g.items.length === 2, JSON.stringify(g));
+  check('T4 reason 逐条点名行号与内容（作者不必回去逐行找）',
+    /第5行「甲」/.test(g.reason) && /第6行「乙」/.test(g.reason), g.reason);
+  check('T4 reason 给出条数 + hint 给两条解决路径（改前缀 / 删行）',
+    /2 处未澄清项/.test(g.reason) && /已澄清/.test(g.hint) && /删行/.test(g.hint), JSON.stringify(g));
+  check('T4 ok=false 时必然带 reason 与 hint（出账完整，勿半截）', !!g.reason && !!g.hint);
+
+  fs.writeFileSync(p, '---\n状态: draft\n---\n# S\n- 已澄清：都解决了\n');
+  const g2 = clarifyGateFor(p);
+  check('T4 全部已澄清 → ok=true', g2.ok && g2.items.length === 0, JSON.stringify(g2));
+
+  const missing = clarifyGateFor(path.join(tmp, 'nope.md'));
+  check('T4 文件不可读 → ok=true + skipped=unreadable（fail-open，不因读不到而拒确认）',
+    missing.ok && missing.skipped === 'unreadable', JSON.stringify(missing));
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) { console.log('\n用法：node templates/_agents/scripts/stage-gates.test.mjs'); process.exit(1); }
+process.exit(0);

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

@@ -209,6 +209,40 @@ for (const m2 of html.matchAll(/href="([^"]+)"/g)) {
 }
 if (deadLinks.length) problems.push(`看板链接指向不存在的路径（相对 wiki/ 解析）: ${deadLinks.join('；')}`);
 
+// ---- 9. 来源血缘（B3，2026-10-10）：wiki frontmatter「来源: workflow/<类型>/<文件>」指回 workflow 归档 ----
+// 与 intent/incident 的正向「沉淀:」字段对称闭环——双向链接任一端指向不存在的文件即断链。
+// 校验面：活跃层知识文档（.md/.html，含子目录递归）。无 frontmatter / 无来源键的老文件零影响。
+// drafts-archive 草稿的来源校验降级为提示（草稿是中间态，来源 intent 可能尚未在仓库——B2 落的草稿
+//   在 intent done 前生成，此时断链属预期），不进 problems。
+// 注意：activeTree 只含活跃主题目录（drafts-archive 在枚举处被排除），草稿须另行扫描归档树。
+const fmGet = (text, key) => {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const kv = m[1].split(/\r?\n/).map((l) => l.match(/^(\S+):\s*(.*)$/)).find((x) => x && x[1] === key);
+  return kv ? kv[2].trim() : null;
+};
+let brokenSources = 0;
+const checkSource = (f, isDraft) => {
+  let text;
+  try { text = fs.readFileSync(path.join(WIKI, f), 'utf8'); } catch { return; }
+  const src = fmGet(text, '来源');
+  if (!src) return;
+  if (fs.existsSync(src)) return;
+  if (isDraft) notes.push(`草稿 ${f} 来源未落地（草稿中间态，归类前允许）：${src}`);
+  else { problems.push(`来源断链：${f} frontmatter「来源: ${src}」指向的文件不存在`); brokenSources++; }
+};
+for (const f of activeTree.files) {
+  if (!/\.(md|html)$/i.test(f)) continue;
+  checkSource(f, false);
+}
+if (fs.existsSync(ARCHIVE_DIR)) {
+  for (const f of walkTree(ARCHIVE_DIR).files) {
+    if (!/\.(md|html)$/i.test(f)) continue;
+    checkSource(`drafts-archive/${f}`, true);
+  }
+}
+if (brokenSources === 0) notes.push('来源血缘有效：活跃层 wiki 文件的「来源」均指向存在的 workflow 归档');
+
 // ---- 输出 ----
 for (const n of notes) console.log('ℹ️  ' + n);
 if (problems.length) {