agentic-flow-kit 1.6.0 → 1.7.15

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

@@ -7,6 +7,11 @@
 //   ④ kit.json 无 owned 字段 → skipped=true total=0
 // 另测 checkAdapterDrift(target)（场景 5-14）与 checkLedgerCoverage(target, pkgRoot)（场景 15-18，
 //   2026-09-26 managed-ledger-adopt：补「盘上有、台账无」一侧）。
+// 另测 checkDelegationSnapshotFreshness(target)（场景 19-23，2026-09-29 p0-gate-noise-batch）与
+//   checkGateAnchors(target)（场景 24-30，2026-10-11 P3-1 gate 防改锚：add-gate 写下的 srcSha256 锚让
+//   .agents/hooks/ 门禁脚本手改永久可见；local-pre-commit 模板语义锚须排除出比对面）。
+// 另测 checkTemplateDrift(target, pkgRoot)（场景 31-36，2026-10-11 模板感知直测补齐——此前唯一无直测的
+//   导出 check：三态判定 + 排除面 + 无模板跳过）。
 // 用法：node .agents/scripts/doctor.test.mjs（在仓库根执行，需 src/doctor.mjs 存在——dogfooding 模式）
 import fs from 'node:fs';
 import os from 'node:os';
@@ -27,7 +32,7 @@ if (!fs.existsSync(SRC)) {
   console.error(`doctor.test.mjs：SKIP——未找到 ${SRC}（装户环境无包源 src/；本套件仅在包源仓库/dogfooding 跑 npm test 时有意义）`);
   process.exit(0);
 }
-const { checkOwnedDrift, checkAdapterDrift, checkLedgerCoverage, checkDelegationSnapshotFreshness } = await import(pathToFileURL(SRC).href);
+const { checkOwnedDrift, checkAdapterDrift, checkLedgerCoverage, checkDelegationSnapshotFreshness, checkGateAnchors, checkTemplateDrift, gateTrustOf, GATE_TRUST_LEVELS, GATE_TRUST_DEFAULT } = await import(pathToFileURL(SRC).href);
 
 let pass = 0;
 let fail = 0;
@@ -473,5 +478,250 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 24-30：checkGateAnchors（2026-10-11 P3-1 gate 防改锚）—— .agents/hooks/ 门禁脚本安装锚 ----
+// 锚语义（见 src/add-gate.mjs 头注）：add-gate 逐字拷贝安装时写 srcSha256＝安装时刻包源 LF 归一 sha；
+// sync 自愈 sha256 但从不按盘面刷新 gate 条目的 srcSha256（srcTemplatePath 解析不到包源模板提前 return）
+// → 盘面 sha ≠ 锚即「装后手改」，doctor 出 WARN 留痕（不阻断——装户对门有最终所有权，锚只提供可见性）。
+const GATE_A = '.agents/hooks/check-test-protect.mjs';
+const GATE_B = '.agents/hooks/check-node-layer.mjs';
+const GATE_BODY = '// gate v1\n';
+
+// ---- 场景 24：锚完好 → PASS 语义（skipped=false mismatch=[] gone=[] total=带锚数）----
+{
+  const root = mkfix({
+    kitContent: mkKit([{ rel: GATE_A, sha256: sha256Of(GATE_BODY), srcSha256: sha256Of(GATE_BODY) }]),
+    files: { [GATE_A]: GATE_BODY },
+  });
+  const r = checkGateAnchors(root);
+  check('场景 24：gate 锚完好 → mismatch=0 gone=0 total=1 skipped=false',
+    r.skipped === false && r.mismatch.length === 0 && r.gone.length === 0 && r.total === 1,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 25：篡改带锚 gate 文件 → mismatch=[rel]（手改永久留痕——本单的目标形态）----
+{
+  const root = mkfix({
+    kitContent: mkKit([{ rel: GATE_A, sha256: sha256Of(GATE_BODY), srcSha256: sha256Of(GATE_BODY) }]),
+    files: { [GATE_A]: '// gate v1 本地手改：放宽红线\n' }, // 盘面 ≠ 安装时刻包源
+  });
+  const r = checkGateAnchors(root);
+  check('场景 25：手改带锚 gate → mismatch 含该件 skipped=false',
+    r.skipped === false && r.mismatch.length === 1 && r.mismatch[0] === GATE_A,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 26：混合面——完好 / 失配 / 缺失并存 → mismatch 与 gone 各归各位，total＝带锚条目数 ----
+{
+  const root = mkfix({
+    kitContent: mkKit([
+      { rel: GATE_A, sha256: sha256Of(GATE_BODY), srcSha256: sha256Of(GATE_BODY) },  // 完好
+      { rel: GATE_B, sha256: sha256Of(GATE_BODY), srcSha256: sha256Of(GATE_BODY) },  // 缺失（不落盘）
+    ]),
+    files: { [GATE_A]: GATE_BODY },
+  });
+  const r = checkGateAnchors(root);
+  check('场景 26：完好+缺失并存 → gone=[GATE_B] mismatch=[] total=2',
+    r.skipped === false && r.gone.length === 1 && r.gone[0] === GATE_B && r.mismatch.length === 0 && r.total === 2,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 27：无带锚条目（旧装户 owned 无 srcSha256 / 非 hooks 条目）→ skipped=true 静默 ----
+{
+  const root = mkfix({
+    kitContent: mkKit([
+      { rel: GATE_A, sha256: sha256Of(GATE_BODY) }, // 旧装户：无锚
+      { rel: 'AGENTS.md', sha256: sha256Of('# a\n') }, // 非 hooks 条目不参与
+    ]),
+    files: { [GATE_A]: GATE_BODY, 'AGENTS.md': '# a\n' },
+  });
+  const r = checkGateAnchors(root);
+  check('场景 27：无带锚 gate 条目 → skipped=true（旧装户重装 add-gate 后生效）',
+    r.skipped === true && r.total === 0,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 28：local-pre-commit 模板语义锚不参与比对（防恒失配误报）----
+// 它的 srcSha256 由 init/sync 按「模板语义」写（锚＝templates/_agents/hooks/local-pre-commit），
+// 盘面含各门挂载行 ≠ 模板——纳入比对面必恒失配，须排除（见 checkGateAnchors 注释）。
+{
+  const LP_WIRED = '#!/bin/sh\nset -e\nnode .agents/hooks/check-test-protect.mjs\n'; // 接线后盘面
+  const root = mkfix({
+    kitContent: mkKit([
+      { rel: '.agents/hooks/local-pre-commit', sha256: sha256Of(LP_WIRED), srcSha256: sha256Of('#!/bin/sh\nset -e\n') },
+    ]),
+    files: { '.agents/hooks/local-pre-commit': LP_WIRED },
+  });
+  const r = checkGateAnchors(root);
+  check('场景 28：local-pre-commit（模板锚+接线盘面）不纳入 → skipped=true 不误报',
+    r.skipped === true && r.total === 0,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 29：kit.json 解析失败 → skipped=true 含 error（沿用 §6.6 同款跳过语义）----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-gateanchor-'));
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), '{ broken json');
+  const r = checkGateAnchors(root);
+  check('场景 29：kit.json 解析失败 → skipped=true 含 error',
+    r.skipped === true && typeof r.error === 'string' && r.error.length > 0,
+    JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 30：主流程渐进路径源断言（同场景 8 手法）——§6.6b 失配分支按信任档分级 ----
+// 默认档（gateTrust=project）= WARN（「先 WARN 升级 FAIL」渐进路径）：装户可改门禁，锚只提供可见性。
+// org 档（2026-10-12 gate-trust-level）= FAIL —— 组织级强制位。断言的是**分级存在**，不是写死某档。
+{
+  const doctorSrc = fs.readFileSync(SRC, 'utf8');
+  const lvMatch = /gateRes\.mismatch\.length\)\s*add\((lv)/.test(doctorSrc);
+  const lvDef = /const lv = orgMode \? 'FAIL' : 'WARN'/.test(doctorSrc);
+  check('场景 30a：§6.6b gate 锚失配分支按信任档分级（lv 常量，不写死单档）',
+    lvMatch && lvDef,
+    `src/doctor.mjs §6.6b 失配分支应为 add(lv, ...) 且 lv = orgMode ? 'FAIL' : 'WARN'`);
+  check('场景 30b：失配出账含「gate 安装锚失配」字样（含重装重锚/恢复原版指引）',
+    doctorSrc.includes('gate 安装锚失配') && doctorSrc.includes('add-gate <门名> --force'),
+    'src/doctor.mjs §6.6b 文案缺失');
+  check('场景 30c：无带锚条目 → PASS 跳过语义（旧装户静默）',
+    doctorSrc.includes('无带锚 gate 条目'),
+    'src/doctor.mjs §6.6b 应有无锚跳过 PASS 分支');
+  // 函数体切取：checkGateAnchors 声明行起、下一个 export function 止（JSDoc 不参与断言）
+  const fnStart = doctorSrc.indexOf('export function checkGateAnchors');
+  const fnEnd = doctorSrc.indexOf('export function', fnStart + 10);
+  check('场景 30d：local-pre-commit 排除在比对面外（防模板锚恒失配误报）',
+    fnStart >= 0 && fnEnd > fnStart && doctorSrc.slice(fnStart, fnEnd).includes("'.agents/hooks/local-pre-commit'"),
+    'checkGateAnchors 应排除 .agents/hooks/local-pre-commit');
+}
+
+// ---- 场景 37-42：gateTrustOf 信任档（2026-10-12 gate-trust-level）----
+// 反例钉子核心：**非法值 / 缺键必须回退 project（零行为变化），绝不因非法配置变严**
+// ——把默认升 org 是另一个决定；让「写错一个字符串」自动升到组织级强制则是配置事故。
+{
+  check('场景 37：显式 project / org 均如实返回',
+    gateTrustOf({ gateTrust: 'project' }) === 'project' && gateTrustOf({ gateTrust: 'org' }) === 'org');
+  check('场景 38：缺键（旧台账）/ null / undefined / 无 kit → 回退 project（零行为变化）',
+    gateTrustOf({}) === 'project' && gateTrustOf({ gateTrust: undefined }) === 'project'
+      && gateTrustOf(null) === 'project' && gateTrustOf(undefined) === 'project');
+  check('场景 39：非法值全部回退 project（大小写错、自造档、数字、数组皆同）',
+    gateTrustOf({ gateTrust: 'ORG' }) === 'project' && gateTrustOf({ gateTrust: 'organization' }) === 'project'
+      && gateTrustOf({ gateTrust: 1 }) === 'project' && gateTrustOf({ gateTrust: ['org'] }) === 'project');
+  check('场景 40：默认值常量与档位表同源一致（init 写 kit.json 用的就是它）',
+    GATE_TRUST_DEFAULT === 'project' && GATE_TRUST_LEVELS.join(',') === 'project,org');
+
+  // 端到端：kit.json 带 gateTrust → checkGateAnchors 回读该档（判据确实消费了它）
+  const mkTrustKit = (gateTrust) => ({
+    ...mkKit([{ rel: GATE_A, sha256: sha256Of(GATE_BODY), srcSha256: sha256Of(GATE_BODY) }]),
+    ...(gateTrust === undefined ? {} : { gateTrust }),
+  });
+  for (const [label, gt, want] of [
+    ['显式 org → 回读 org', 'org', 'org'],
+    ['显式 project → 回读 project', 'project', 'project'],
+    ['缺键（旧装户）→ 回读 project', undefined, 'project'],
+    ['非法值 → 回读 project', 'ORG', 'project'],
+  ]) {
+    const root = mkfix({ kitContent: mkTrustKit(gt), files: { [GATE_A]: '// 手改\n' } });
+    const r = checkGateAnchors(root);
+    check(`场景 41 ${label}（且失配仍照常检出）`, r.trust === want && r.mismatch.length === 1,
+      JSON.stringify({ want, got: r.trust, mismatch: r.mismatch }));
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ---- 场景 31-36：checkTemplateDrift（2026-10-11 模板感知直测补齐——此前唯一无直测的导出 check）----
+// 三态判定单源 profiles.templateDriftOf：synced（盘==当前源）/ stale-drift（源演进盘未跟，唯一出账）/
+// custom-synced（盘定制、源==锚，永不告警）/ no-anchor（旧装户静默）；TEMPLATE_DRIFT_EXCLUDE 与
+// 无对应模板 rel 均不入比对面。fixture 双根：target（.agents/kit.json + 盘面）+ pkgRoot（templates/）。
+{
+  const OLD_BODY = '# tpl v1\n';
+  const NEW_BODY = '# tpl v2 — source evolved\n';
+  const CUSTOM_BODY = '# hand-customized\n';
+  const mkpkg = (tplContent) => {
+    const pkg = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-tpl-pkg-'));
+    fs.mkdirSync(path.join(pkg, 'templates'), { recursive: true });
+    if (tplContent !== null) fs.writeFileSync(path.join(pkg, 'templates', 'AGENTS.md'), tplContent);
+    return pkg;
+  };
+  // 31 盘面 == 当前源 → synced，零 stale
+  {
+    const pkg = mkpkg(OLD_BODY);
+    const root = mkfix({
+      kitContent: mkKit([{ rel: 'AGENTS.md', sha256: sha256Of(OLD_BODY), srcSha256: sha256Of(OLD_BODY) }]),
+      files: { 'AGENTS.md': OLD_BODY },
+    });
+    const r = checkTemplateDrift(root, pkg);
+    check('场景 31：盘面==当前源 → synced（skipped=false stale=[] total=1）',
+      r.skipped === false && r.total === 1 && r.stale.length === 0, JSON.stringify(r));
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(pkg, { recursive: true, force: true });
+  }
+  // 32 源演进 + 盘面未跟 → stale-drift（唯一出账形态）
+  {
+    const pkg = mkpkg(NEW_BODY);                       // 包源已演进
+    const root = mkfix({
+      kitContent: mkKit([{ rel: 'AGENTS.md', sha256: sha256Of(OLD_BODY), srcSha256: sha256Of(OLD_BODY) }]),
+      files: { 'AGENTS.md': OLD_BODY },                // 盘面还停在锚版本
+    });
+    const r = checkTemplateDrift(root, pkg);
+    check('场景 32：源演进盘未跟 → stale-drift（stale=[AGENTS.md]）',
+      r.skipped === false && r.stale.length === 1 && r.stale[0] === 'AGENTS.md', JSON.stringify(r));
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(pkg, { recursive: true, force: true });
+  }
+  // 33 盘面定制（源==锚）→ custom-synced，永不告警
+  {
+    const pkg = mkpkg(OLD_BODY);
+    const root = mkfix({
+      kitContent: mkKit([{ rel: 'AGENTS.md', sha256: sha256Of(CUSTOM_BODY), srcSha256: sha256Of(OLD_BODY) }]),
+      files: { 'AGENTS.md': CUSTOM_BODY },
+    });
+    const r = checkTemplateDrift(root, pkg);
+    check('场景 33：盘面定制源==锚 → custom-synced（stale=[] 不出账）',
+      r.skipped === false && r.total === 1 && r.stale.length === 0, JSON.stringify(r));
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(pkg, { recursive: true, force: true });
+  }
+  // 34 无 srcSha256 锚（旧装户）→ skipped 静默不追溯
+  {
+    const pkg = mkpkg(OLD_BODY);
+    const root = mkfix({
+      kitContent: mkKit([{ rel: 'AGENTS.md', sha256: sha256Of(OLD_BODY) }]),
+      files: { 'AGENTS.md': OLD_BODY },
+    });
+    const r = checkTemplateDrift(root, pkg);
+    check('场景 34：无锚 → skipped=true（旧装户静默，下次 sync 写锚生效）',
+      r.skipped === true && r.total === 0 && r.stale.length === 0, JSON.stringify(r));
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(pkg, { recursive: true, force: true });
+  }
+  // 35 生成器目标（TEMPLATE_DRIFT_EXCLUDE）排除出比对面——混合条目只计 AGENTS.md
+  {
+    const pkg = mkpkg(OLD_BODY);
+    const root = mkfix({
+      kitContent: mkKit([
+        { rel: 'workflow/INDEX.md', sha256: sha256Of('# idx\n'), srcSha256: sha256Of('# idx\n') },
+        { rel: 'AGENTS.md', sha256: sha256Of(OLD_BODY), srcSha256: sha256Of(OLD_BODY) },
+      ]),
+      files: { 'AGENTS.md': OLD_BODY },
+    });
+    const r = checkTemplateDrift(root, pkg);
+    check('场景 35：生成器目标排除 → total=1 只计 AGENTS.md',
+      r.skipped === false && r.total === 1 && r.stale.length === 0, JSON.stringify(r));
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(pkg, { recursive: true, force: true });
+  }
+  // 36 rel 无对应模板（srcTemplatePath null）→ 不入比对面
+  {
+    const pkg = mkpkg(OLD_BODY);
+    const root = mkfix({
+      kitContent: mkKit([{ rel: 'wiki/自定文档.md', sha256: sha256Of('# x\n'), srcSha256: sha256Of('# x\n') }]),
+      files: {},
+    });
+    const r = checkTemplateDrift(root, pkg);
+    check('场景 36：无对应模板 rel → 不计数（skipped=true）',
+      r.skipped === true && r.total === 0, JSON.stringify(r));
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(pkg, { recursive: true, force: true });
+  }
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/draft-sediment.mjs

@@ -0,0 +1,178 @@
+// flow-kit draft-sediment：关单时把高价值内容自动抽成 wiki 草稿（B2，2026-10-10）
+// 输入：一个 done intent 或 closed incident 文件 → 抽取高价值节（影响面/触达红线 或 复盘三件套）
+//   → 渲染成带「来源」frontmatter 的 wiki 草稿 → 落 wiki/drafts-archive/<日期-主题>/<主题>.md
+//   → 回写源文件 frontmatter「沉淀:」字段（与 B1 沉淀追踪闭环）→ 重跑 gen-wiki-board（归档计数随动，
+//     否则 verify-wiki-consistency 的 summary.archive 比对会拦提交）
+// 草稿是中间态：drafts-archive 只读不增量、不参与文件级登记（仅计总数），归类到活跃主题目录由人工完成
+// （人工移动后跑 gen-wiki-board + verify-wiki-consistency，并在目标文件保留/改写「来源」字段）
+// 用法：node .agents/scripts/draft-sediment.mjs workflow/intents/<日期>-<主题>.md [--dry-run] [--help]
+//   （intent 须 done；incident 须 closed 且复盘三件套齐全——与 check-loop 沉淀追踪子判据同口径）
+// 零依赖；抽节为纯函数（export 供测试）；CLI 解析最简字符串匹配
+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 USAGE = `用法：node .agents/scripts/draft-sediment.mjs <workflow/intents|incidents/文件.md> [--dry-run] [--help]
+
+关单时把高价值内容抽成 wiki 草稿（B2 沉淀自动化）：
+  - intent（须 done）：抽「影响面」「触达红线」节
+  - incident（须 closed 且复盘三件套齐全）：抽「影响面」「根因」「为什么之前没拦住」「复盘三件套」节
+落 wiki/drafts-archive/<日期-主题>/<主题>.md，带「来源」frontmatter 指回源文件（B3 双向链接），
+并回写源文件 frontmatter「沉淀:」字段（B1 闭环），随后重跑 gen-wiki-board.mjs 更新归档计数。
+
+选项：
+  --dry-run   只打印将生成的草稿与回写动作，不写盘
+  --help      打印本说明
+
+草稿是中间态：drafts-archive 只读不增量。人工归类到 wiki/<主题>/ 后跑
+  node .agents/scripts/gen-wiki-board.mjs && node .agents/scripts/verify-wiki-consistency.mjs`;
+
+// extractSections：从 markdown 抽指定节（## 标题到下一 ## 之间的非空正文）。纯函数，无 IO。
+//   节标题前缀匹配（兼容「## 影响面与边界」）。占位行（<…> 单行包揽 / HTML 注释 / 引用块）剔除——
+//   与 check-loop sectionHasBody 同口径：模板未填段抽出的是占位，没有沉淀价值。
+//   返回 [{ title, body }]，body 为去占位后的非空行拼接（保留原行内容与缩进）。
+export function extractSections(text, headings) {
+  const lines = String(text).split(/\r?\n/);
+  const out = [];
+  let cur = null;
+  let buf = [];
+  const flush = () => {
+    if (cur) {
+      const body = buf.filter((l) => {
+        const s = l.trim();
+        return s && !/^<.*>$/.test(s) && !s.startsWith('<!--') && !s.startsWith('>');
+      });
+      if (body.length) out.push({ title: cur, body: body.join('\n') });
+    }
+    buf = [];
+  };
+  for (const line of lines) {
+    const h = line.match(/^\s*##\s+(.+?)\s*$/);
+    if (h) {
+      flush();
+      cur = headings.find((x) => h[1].startsWith(x)) ? h[1] : null;
+      continue;
+    }
+    if (cur) buf.push(line);
+  }
+  flush();
+  return out;
+}
+
+// topicOf：主题取法——标题行（# INTENT — <主题>）优先（文件名主题常是英文短代称，
+//   标题才是可读中文名）；无标题行再退文件名尾段（YYYY-MM-DD-<主题>）；都无取文件基名。
+export function topicOf(filePath, text) {
+  const t = String(text).match(/^#\s+(?:INTENT|INCIDENT|PLAN|SPEC)\s*—\s*(.+?)\s*$/m);
+  if (t) return t[1];
+  const base = path.basename(filePath, '.md');
+  const m = base.match(/^\d{4}-\d{2}-\d{2}-(.+)$/);
+  return m ? m[1] : base;
+}
+
+// renderDraft：草稿渲染（纯函数）。date = 落盘日期（YYYY-MM-DD），source = 来源相对仓根路径。
+export function renderDraft({ topic, date, source, sections, kind }) {
+  const fm = `---\n来源: ${source}\n状态: 草稿（待人工归类）\n---\n`;
+  const kindLabel = kind === 'incident' ? '事故复盘' : '需求沉淀';
+  let body = `# ${topic}（${kindLabel}草稿）\n`;
+  body += `> 自动抽取于 ${date}，源自 \`${source}\`（关单沉淀，B2）。`;
+  body += `本文件是**中间态**——归类到 wiki/<主题>/ 后补主题、用途，并保留「来源」字段。\n\n`;
+  for (const s of sections) {
+    body += `## ${s.title}\n\n${s.body}\n\n`;
+  }
+  return fm + body;
+}
+
+// setSedimentField：回写源文件 frontmatter「沉淀:」字段。已有值（非空、非「无」）不覆盖（防误抹人工登记）。
+export function setSedimentField(text, value) {
+  const m = String(text).match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
+  if (!m) return { text, changed: false };
+  const fmBody = m[2];
+  const lines = fmBody.split(/\r?\n/);
+  const idx = lines.findIndex((l) => /^沉淀:\s*/.test(l));
+  if (idx >= 0) {
+    const cur = lines[idx].replace(/^沉淀:\s*/, '').trim();
+    if (cur && cur !== '无') return { text, changed: false }; // 已有人工登记，不覆盖
+    lines[idx] = `沉淀: ${value}`;
+  } else {
+    lines.push(`沉淀: ${value}`);
+  }
+  return { text: m[1] + lines.join('\n') + m[3] + String(text).slice(m[0].length), changed: true };
+}
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const isMain = process.argv[1] && process.argv[1].endsWith('draft-sediment.mjs');
+if (isMain) {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) { console.log(USAGE); process.exit(0); }
+  const DRY = args.includes('--dry-run');
+  const target = args.find((a) => !a.startsWith('-'));
+  if (!target) fail('必填：源文件路径（workflow/intents/… 或 workflow/incidents/…）' + '\n\n' + USAGE);
+  if (!fs.existsSync(target)) fail('源文件不存在：' + target);
+
+  const text = fs.readFileSync(target, 'utf8');
+  const rel = path.relative(process.cwd(), target).split(path.sep).join('/');
+  const kind = rel.startsWith('workflow/incidents/') ? 'incident' : rel.startsWith('workflow/intents/') ? 'intent' : null;
+  if (!kind) fail('源文件须在 workflow/intents/ 或 workflow/incidents/ 下：' + rel);
+
+  // 状态校验（与 check-loop 沉淀追踪子判据同口径）
+  const fmStatus = (() => {
+    const m = text.match(/^---\r?\n[\s\S]*?^状态:\s*(.+?)\s*$/m);
+    return m ? m[1].trim() : null;
+  })();
+  if (kind === 'intent' && fmStatus !== 'done') fail('intent 须为 done 才沉淀（当前：' + (fmStatus || '缺失') + '）');
+  if (kind === 'incident' && fmStatus !== 'closed') fail('incident 须为 closed 才沉淀（当前：' + (fmStatus || '缺失') + '）');
+
+  // 抽节：intent 影响面/触达红线；incident 影响面/根因/为什么之前没拦住/复盘三件套
+  const HEADINGS = kind === 'incident'
+    ? ['影响面', '根因', '为什么之前没拦住', '复盘三件套']
+    : ['影响面', '触达红线'];
+  const sections = extractSections(text, HEADINGS);
+  if (!sections.length) fail('未抽取到高价值节（' + HEADINGS.join('/') + ' 均为空或仅占位）——内容无沉淀价值，停止');
+
+  const topic = topicOf(target, text);
+  const date = new Date().toISOString().slice(0, 10);
+  const draftDir = path.join('wiki', 'drafts-archive', `${date}-${topic}`);
+  const draftPath = path.join(draftDir, `${topic}.md`);
+  const draft = renderDraft({ topic, date, source: rel, sections, kind });
+
+  // 回写源文件沉淀字段（草稿路径相对仓根）
+  const { text: newText, changed } = setSedimentField(text, draftPath.split(path.sep).join('/'));
+
+  if (DRY) {
+    console.log('🔎 --dry-run：未写盘');
+    console.log(`• 将生成草稿：${draftPath}（${sections.length} 节 / ${draft.length} 字节）`);
+    console.log(`• 将回写 ${rel} frontmatter「沉淀: ${draftPath.split(path.sep).join('/')}」${changed ? '' : '（已有登记，不覆盖）'}`);
+    console.log('• 将重跑 gen-wiki-board.mjs（归档计数 +1）');
+    console.log('\n--- 草稿预览（前 30 行）---');
+    console.log(draft.split(/\r?\n/).slice(0, 30).join('\n'));
+    process.exit(0);
+  }
+
+  // 写草稿
+  fs.mkdirSync(draftDir, { recursive: true });
+  fs.writeFileSync(draftPath, draft);
+  console.log(`✅ 已生成 wiki 草稿：${draftPath}（${sections.length} 节：${sections.map((s) => s.title).join('、')}）`);
+
+  // 回写源文件
+  if (changed) {
+    fs.writeFileSync(target, newText);
+    console.log(`✅ 已回写源文件沉淀字段：${rel} → 沉淀: ${draftPath.split(path.sep).join('/')}`);
+  } else {
+    console.log(`ℹ️ 源文件已有沉淀登记，未覆盖：${rel}`);
+  }
+
+  // 重跑 gen-wiki-board（归档计数随动——不跑则 verify-wiki-consistency 的 summary.archive 比对拦提交）
+  const gen = path.join(SCRIPT_DIR, 'gen-wiki-board.mjs');
+  if (fs.existsSync(gen)) {
+    const r = spawnSync(process.execPath, [gen], { encoding: 'utf8', windowsHide: true });
+    if (r.status === 0) console.log('✅ 已重跑 gen-wiki-board.mjs（归档计数随动）');
+    else console.error('⚠️ gen-wiki-board.mjs 重跑失败（exit ' + r.status + '）——手工跑：node .agents/scripts/gen-wiki-board.mjs');
+  } else {
+    console.log('ℹ️ gen-wiki-board.mjs 不存在（旧装户），跳过归档计数随动');
+  }
+  console.log('\n下一步（人工）：读草稿 → 归类到 wiki/<主题>/ → 补主题与用途 → 跑 gen-wiki-board + verify-wiki-consistency');
+}