agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/scripts/fill-plan.mjs

@@ -0,0 +1,105 @@
+// fill-plan：起草 plan 草稿（L1 五节或 --lite 三节且 plan 即入口 / L2-L3 完整 4 节）
+// 用法：node .agents/scripts/fill-plan.mjs --level L1 --topic "test" --output /tmp/x.md [--lite] [--root <仓库根>]
+// L1：入口 + 改动方案 + 约束与风险 + 验证计划 + 验收标准（不另立 intent）
+// L1 --lite：入口 + 改动方案 + 验证与验收（三节；适用条件：检索无 incident 命中且红线全不勾）
+// L2/L3：改动方案 + 任务拆解 + 执行顺序 + 验证计划
+// 起草门（stage-gate-machine）：output 落于工作区（路径含 workflow 段）时，须同主题入口已确认，
+// 且入口级别（取入口 frontmatter，非 --level）为 L2/L3 时同名 spec 已确认；未过 → 拒绝生成（exit 2）。
+// L1 例外（2026-10-10）：无同名 intent/incident 时 plan 自己就是入口，--level L1 直接生成。
+import fs from 'node:fs';
+import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
+import { draftGateFor, resolveWorkspace } from './stage-gates.mjs';
+
+const TODAY = new Date().toISOString().slice(0, 10);
+const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/config/workflow-enums.txt）
+
+function parseArgs(argv) {
+  const out = { topic: null, level: 'L1', output: null, root: null, lite: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
+    if (a === '--topic') out.topic = next();
+    else if (a === '--level') out.level = next();
+    else if (a === '--output') out.output = next();
+    else if (a === '--root') out.root = next();
+    else if (a === '--lite') out.lite = true;
+  }
+  return out;
+}
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const L1_ENTRY = {
+  title: '入口',
+  hint: '- 来源：<工单 / 对话 / 事故>\n- 目标：<可验证的一句话>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）→ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 → 级别 L3\n\n> 勾选任一行就把本 plan 级别升到 L2/L3，并补同名 intent + spec。未勾选即 L1，不再另立 intent。',
+};
+const L1_ACCEPTANCE = {
+  title: '验收标准（可测试）',
+  hint: '- [ ] <逐条可测试；写不出判据 = 还没想清楚>\n\n> 关单前逐条勾验并补证据：`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟输出>）`。',
+};
+const L1_SECTIONS = [
+  L1_ENTRY,
+  { title: '改动方案', hint: '- <文件/组件>：<做什么；判据细节直接写进条目，如「L771 message.success 改『更新成功』」>\n\n> L2/L3：本节作总清单；任务拆解每步再写「- 文件：…」与判据，否则全景图只能把文件归到附录。\n> stages.md Build §2 确认的改动清单确认后回填本节落盘（对话留痕仅供当次）——改动面 + 任务勾选态 + git status = 会话重入三锚（session-context）。' },
+  { title: '约束与风险', hint: '- 约束：<对照 AGENTS.md 红线，说明如何满足；不许动什么>\n- 风险：<潜在影响 / 破坏性风险>' },
+  { title: '验证计划', hint: '- 静态门：项目构建命令（+ 项目测试命令，测试项目就绪后）\n- 前端：cd frontend && npm run build（vue-tsc）\n- UI：.agents/commands/stages.md Test 章（涉及页面改动必走，headless Chrome 实测）\n- L2 追加：<契约 / 规则面比对：编码结果抽样 / 接口契约断言 / 口径对账>\n- L3 追加：<含 schema 变更：备份 + 回滚 SQL 就绪后执行；仅运行时 / 管线：回退上一 release tag + 配置开关预案>' },
+  L1_ACCEPTANCE,
+];
+
+const L1_LITE_SECTIONS = [
+  L1_ENTRY,
+  L1_SECTIONS[1],
+  {
+    title: '验证与验收（lite）',
+    hint: '- 静态门：`node .agents/scripts/verify.mjs --scope` 绿（涉前端改动另附实测证据）\n- 检索：粘贴第 2 步 kb-search 输出（无命中贴命令与空结果即可，免另写说明）\n- 验收：\n- [ ] <逐条可测试；写不出判据 = 还没想清楚>\n\n> 关单前逐条勾验并补证据：`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟输出>）`。约束与风险以一句话并入改动方案条目。',
+  },
+];
+
+const FULL_SECTIONS = [
+  L1_SECTIONS[1],
+  { title: '任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）', hint: '- [ ] 1. <任务>\n   - 文件：<本步会改的文件路径；每步至少一个；纯验证步骤写「验证步骤：无代码文件」>\n   - 判据：<怎样算完成；尽量对应一个测试或可复现操作>\n   - 风险：低 / 中 / 高（<原因>）\n   - 留痕：（勾选时回填 commit SHA / 测试名 / 实测输出）\n- [ ] 2. <任务>\n   - 文件：…\n   - 判据：…\n   - 风险：…\n   - 留痕：…\n\n> 每步「文件」是开发全景图 步骤×文件 对齐的单源；实现步骤缺文件条目会被 `gen-dev-tour --strict` 拒绝，纯验证步骤请在标题写明「验证步骤」。\n> 任务即勾选态（session-context）：完成一项立刻勾选并回填留痕；压缩 / 新会话续作先读本表勾选态 + git status 重建进度，禁凭记忆补勾。' },
+  { title: '执行顺序（L2/L3 必填；L1 单文件微改动删本节）', hint: '<1 → 2 → 3；标注依赖关系>' },
+  L1_SECTIONS[3],
+];
+
+export function renderPlan({ topic, level = 'L1', date = TODAY, lite = false }) {
+  if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
+  const sections = level === 'L1' ? (lite ? L1_LITE_SECTIONS : L1_SECTIONS) : FULL_SECTIONS;
+  // 日期写进 frontmatter（2026-10-27）：此前 renderPlan 收了 date 参数却从不落 frontmatter，
+  // 致 plan 无「日期」字段——委派台账在场门（confirm-doc）与检查 18 均以日期为适用前提，
+  // 缺日期即整段跳过 = 本门对绝大多数 L2/L3 plan 静默失效。文件名兜底为第二道保险。
+  const fm = '---\n状态: draft\n级别: ' + level + '\n日期: ' + date + '\n模块: pipeline\n---\n';
+  const entryLine = level === 'L1'
+    ? '对应入口：本 plan（L1 不再另立 intent）。修复类另保留 ../incidents/YYYY-MM-DD-<主题>.md\n对应 spec：省略\n\n'
+    : '对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）\n对应 spec：../specs/YYYY-MM-DD-<主题>.md\n\n';
+  let body = '# PLAN — ' + topic + '\n\n<!-- L2/L3 与 intents/ 或 incidents/ 下同名入口配对，且须先有 ../specs/ 同名 spec；L1 本文件即入口 -->\n<!-- frontmatter 受限子集：状态∈draft/approved/done/superseded/cancelled；级别∈L1/L2/L3；正文不再写状态/级别行 -->\n<!-- L1：一份 plan 收口来源/目标/红线/改动/验证/验收。L2/L3 仍走 intent + spec + 下面 4 节 -->\n\n' + entryLine;
+  for (const { title, hint } of sections) {
+    body += '## ' + title + '\n\n' + hint + '\n\n';
+  }
+  body += '## 确认与复核\n\n> 确认 = 用户在对话内一句话通过；确认后本 plan 状态 draft → approved 并回填本节（确认环节的机器可见态），done 只在关单出现——禁从 draft 直跳 done（papercut）。\n- 确认结果：approved（YYYY-MM-DD 用户对话内确认）；done（YYYY-MM-DD 关单，随入口文档置终态）\n- 确认门记录：plan 草稿全文过目 + 改动清单确认（stages.md Build 两道门，逐次，不合并）\n- 复核：L1 不要求独立复核\n\n> 开发全景：`node .agents/scripts/gen-dev-tour.mjs <本文件>`；看板实时版 `/tour?file=<本文件>`。步骤取「任务拆解/步骤」，文件取任务每步「- 文件：…」或「改动方案」，git 工作树补实际改动（口径 `.agents/skills/dev-tour/SKILL.md`）。\n';
+  return { frontmatter: fm, body: fm + body, sections: sections.map((s) => s.title) };
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('fill-plan.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  if (!a.topic || !a.output) fail('必填：--topic / --output；选填：--level（默认 L1）/ --root');
+  if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
+  if (a.lite && a.level !== 'L1') fail('--lite 仅支持 --level L1');
+  const ws = resolveWorkspace(a.output, a.root);
+  if (ws) {
+    const gate = draftGateFor('plan', ws.root, ws.base, { level: a.level });
+    if (!gate.ok) {
+      console.error('❌ 起草门未过（stage-gates）：' + gate.reason);
+      console.error('   ' + gate.hint + '——本份未生成（确认前置后重跑本命令）');
+      process.exit(2);
+    }
+  } else {
+    console.error('ℹ️  未定位到工作区（output 路径不含 workflow/ 段）——按仓外草稿处理，跳过起草门前置校验');
+  }
+  const { body } = renderPlan(a);
+  fs.mkdirSync(path.dirname(a.output), { recursive: true });
+  fs.writeFileSync(a.output, body);
+  console.log('✅ 已生成 plan 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / ' + (a.level === 'L1' ? (a.lite ? 'L1-lite 三节（plan 即入口）' : 'L1 五节（plan 即入口）') : '完整 4 节') + '）');
+}
+export default renderPlan;

package/templates/engine/.agents/scripts/fill-spec.mjs

@@ -0,0 +1,72 @@
+// fill-spec：起草 spec 草稿（功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 验收判据 / 风险评估 / 前提质询 共 7 节）
+// 用法：node .agents/scripts/fill-spec.mjs --topic "test" --output /tmp/x.md [--root <仓库根>]
+// 起草门（2026-09-30 stage-gate-machine）：output 落于工作区（路径含 workflow 段）时，须同主题入口已确认
+// （判定口径见 stage-gates.mjs）；未过 → 拒绝生成（exit 2）；仓外草稿（无 workflow 段）不校验。
+import fs from 'node:fs';
+import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
+import { draftGateFor, resolveWorkspace } from './stage-gates.mjs';
+
+const TODAY = new Date().toISOString().slice(0, 10);
+const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/config/workflow-enums.txt）
+
+function parseArgs(argv) {
+  const out = { topic: null, level: 'L2', output: null, root: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
+    if (a === '--topic') out.topic = next();
+    else if (a === '--level') out.level = next();
+    else if (a === '--output') out.output = next();
+    else if (a === '--root') out.root = next();
+  }
+  return out;
+}
+
+function fail(msg) { console.error(`❌ ${msg}`); process.exit(1); }
+
+const SECTIONS = [
+  { title: '功能行为', hint: '<完整描述本 spec 涉及的功能 / 行为变化；分用户场景列；含边界与异常>' },
+  { title: '数据流', hint: '<请求→处理→持久化→回应的端到端路径；标出各环节涉及的服务 / 表 / 缓存 / 第三方调用>' },
+  { title: '系统改动', hint: '<分模块列出本 spec 引入的所有改动；含新增 / 修改 / 删除；与 plan §改动面 一一对应>' },
+  { title: '约束遵守映射', hint: '<逐条对照根 AGENTS.md 与目录级 AGENTS.md（如有）的红线 / 约束，说明本 spec 如何满足；逐条回应而非简单列举>' },
+  { title: '验收判据', hint: '<逐条登记可观察行为 × 证据（存在的文件路径，或全量门命令且 verify-evidence.md 有不早于本 spec 日期的全绿行）。人工走查状态写「人工」、证据留空（截图等图片路径不认；需留痕改存 .md 报告后引路径）。检查 23 不核对正文相关性>', table: ['判据（可观察行为）', '证据（测试文件 / 命令 / 证据文件）', '状态'], ph: ['<行为 1>', '<路径或命令>', '<覆盖 / 未覆盖 / 人工>'] },
+  { title: '风险评估', hint: '<列出本 spec 引入的风险点：数据 / 接口 / 性能 / 安全 / 回滚难度 / 用户影响；评估每个的等级与缓解措施>' },
+  { title: '前提质询', hint: '<每行一个立论前提（解读/口径选择，如「展示诉求 vs 存储改写」），反问「换成对立解读会怎样」，结论写凭什么选定（用户原话/文档/实验）；无解读风险的小件写一行「无关键前提」+ 理由。确认门硬拦（premiseSince 锚起）>', table: ['前提', '反问（对立解读会怎样）', '结论与依据'], ph: ['<立论的解读 / 口径选择>', '<换成对立解读会怎样、最坏后果>', '<选定解读 + 凭什么（用户原话 / 文档 / 实验）>'] },
+];
+
+export function renderSpec({ topic, level = 'L2', date = TODAY }) {
+  if (!LEVELS.includes(level)) throw new Error(`level 不在枚举 ${LEVELS.join('|')}：${level}`);
+  const fm = `---\n状态: draft\n级别: ${level}\n日期: ${date}\n模块: pipeline\n备注: <spec 关联 intent / plan 的同名主题>\n---\n`;
+  let body = `# SPEC — ${topic}\n\n<!-- 与 intents/ 下同名入口文档配对；L2/L3 必须先有 ../intents/YYYY-MM-DD-<主题>.md approved -->\n<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled；级别∈L1/L2/L3；正文不再写状态/级别行 -->\n\n`;
+  for (const { title, hint, table, ph } of SECTIONS) {
+    body += `## ${title}\n\n${hint}\n\n`;
+    // 表节（验收判据=检查 23、前提质询=确认门 premiseGate 的机器输入）直出表骨架：
+    // 表头签名固定，作者只填行——占位行被对应门拦收。
+    if (table) body += `| ${table.join(' | ')} |\n|${table.map(() => '---').join('|')}|\n| ${ph.join(' | ')} |\n\n`;
+  }
+  body += `## 确认与复核\n\n- 确认日期：\n- 复核：L3 必须独立复核（independent-reviewer，新会话）；L2 推荐独立复核；L1 可省\n\n> 开发全景：\`node .agents/scripts/gen-dev-tour.mjs <本文件>\`；看板实时版 \`/tour?file=<本文件>\`。步骤取「系统改动」的模块/文件分组，git 工作树补实际改动（口径 \`.agents/skills/dev-tour/SKILL.md\`）。\n`;
+  return { frontmatter: fm, body: fm + body, sections: SECTIONS.map((s) => s.title) };
+}
+
+const isMain = import.meta.url === `file:///${process.argv[1]}` || process.argv[1]?.endsWith('fill-spec.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  if (!a.topic || !a.output) fail('必填：--topic / --output；选填：--level（默认 L2）/ --root');
+  if (!LEVELS.includes(a.level)) fail(`level 必须在 ${LEVELS.join('|')}：${a.level}`);
+  const ws = resolveWorkspace(a.output, a.root);
+  if (ws) {
+    const gate = draftGateFor('spec', ws.root, ws.base);
+    if (!gate.ok) {
+      console.error(`❌ 起草门未过（stage-gates）：${gate.reason}`);
+      console.error(`   ${gate.hint}——本份未生成（确认入口后重跑本命令）`);
+      process.exit(2);
+    }
+  } else {
+    console.error('ℹ️  未定位到工作区（output 路径不含 workflow/ 段）——按仓外草稿处理，跳过起草门前置校验');
+  }
+  const { body } = renderSpec(a);
+  fs.mkdirSync(path.dirname(a.output), { recursive: true });
+  fs.writeFileSync(a.output, body);
+  console.log(`✅ 已生成 spec 草稿：${a.output}（状态 draft / 级别 ${a.level}）`);
+}

package/templates/engine/.agents/scripts/gen-dev-tour.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// gen-dev-tour.mjs — 把 plan/spec 的「步骤 × 改动文件」渲染成可交互开发全景图
+// 用法：
+//   node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md
+//   node .agents/scripts/gen-dev-tour.mjs <doc> --out .agents/cache/tours/x.html
+//   node .agents/scripts/gen-dev-tour.mjs <doc> --base origin/main      # 对比已提交的整段改动
+//   node .agents/scripts/gen-dev-tour.mjs <doc> --json                  # 只打印模型，不写 HTML
+// 默认输出 .agents/cache/tours/<type>-<name>.html（gitignored 的本地快照），并打印看板实时地址。
+// 实时版：node .agents/scripts/ensure-board.mjs → http://127.0.0.1:8933/tour?file=<doc>
+// 口径：文档 = 计划面（步骤/文件），git = 实际面（--base 之后的工作树），两者按路径合并；
+//       实际改了但文档没登记的文件进「文档外实际改动」步骤，不静默丢弃。
+// 零依赖；HTML 模板单源 .agents/board/dev-tour.html，静态快照只在 __TOUR_DATA__ 处注入模型。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildTour, DEFAULT_ROOT } from './dev-tour-model.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = DEFAULT_ROOT;
+const TEMPLATE = path.join(ROOT, '.agents', 'board', 'dev-tour.html');
+
+const USAGE = `用法：node .agents/scripts/gen-dev-tour.mjs <workflow 文档.md> [选项]
+
+把 plan/spec 的步骤与改动文件渲染为单文件 HTML：左侧文件树 / 中间全景图·时序图·数据流图·流程图 / 右侧步骤变更说明。
+
+选项：
+  --out <path>       输出 HTML 路径（默认 .agents/cache/tours/<type>-<name>.html）
+  --base <ref>       git 对比基线（默认 HEAD = 当前工作树未提交改动；已提交任务可传 origin/main 或 <sha>）
+  --all              实际面包含所有改动文件（默认只收 backend/frontend/tests/db/sql/scripts/tools/integration）
+  --include-docs     实际面额外包含 workflow/wiki/.agents 文档改动
+  --no-diff          不嵌入 diff（快照更小；右侧只显示文件与行数）
+  --max-diff-lines   单文件 diff 最多嵌入行数（默认 160）
+  --json             只打印数据模型（供调试/脚本消费）
+  --scope-report     只打印「文档外实际改动」清单（advisory，恒 exit 0；供关单对账）
+  --strict           解析层兜底 / 无步骤 / 实现步骤无文件条目时 exit 1（供门禁化调用；默认 advisory）
+  --help             打印本说明
+
+示例：
+  node .agents/scripts/gen-dev-tour.mjs workflow/plans/2026-11-09-outbound-edit-preserve-line-no.md
+  node .agents/scripts/gen-dev-tour.mjs workflow/plans/2026-11-05-material-guoyu-push.md --base HEAD~20
+  node .agents/scripts/gen-dev-tour.mjs workflow/specs/2026-08-29-code-template-l3-readd-duplicate.md --json`;
+
+function parseArgs(argv) {
+  const out = {
+    doc: '', out: '', base: 'HEAD', all: false, includeDocs: false,
+    withDiff: true, maxDiffLines: 160, json: false, help: false, strict: false, scopeReport: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--out') out.out = argv[++i] || '';
+    else if (a === '--base') out.base = argv[++i] || 'HEAD';
+    else if (a === '--all') out.all = true;
+    else if (a === '--include-docs') out.includeDocs = true;
+    else if (a === '--no-diff') out.withDiff = false;
+    else if (a === '--max-diff-lines') out.maxDiffLines = Math.max(20, Number(argv[++i]) || 160);
+    else if (a === '--json') out.json = true;
+    else if (a === '--scope-report') out.scopeReport = true;
+    else if (a === '--strict') out.strict = true;
+    else if (a.startsWith('-')) { console.error(`❌ 未知参数：${a}\n\n${USAGE}`); process.exit(1); }
+    else if (!out.doc) out.doc = a;
+    else { console.error(`❌ 只接受一个文档参数（多余：${a}）\n\n${USAGE}`); process.exit(1); }
+  }
+  return out;
+}
+
+function escJsonForScript(v) {
+  // 防止文档内容里的 </script> 提前闭合；JSON 仍是合法 JS 字面量
+  return JSON.stringify(v).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+}
+
+function defaultOut(docPath, model) {
+  const base = path.basename(docPath, '.md').replace(/[^\w.\-\u4e00-\u9fa5]+/g, '-');
+  const type = model.doc.type.toLowerCase();
+  return path.join(ROOT, '.agents', 'cache', 'tours', `${type}-${base}.html`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.doc) { console.log(USAGE); process.exit(args.help ? 0 : 1); }
+  if (!fs.existsSync(TEMPLATE)) {
+    console.error(`❌ 模板缺失：${path.relative(ROOT, TEMPLATE)}（引擎文件不完整）`);
+    process.exit(1);
+  }
+  let model;
+  try {
+    model = buildTour({
+      root: ROOT,
+      docPath: args.doc,
+      base: args.base,
+      includeAll: args.all,
+      includeDocs: args.includeDocs,
+      withDiff: args.withDiff,
+      maxDiffLines: args.maxDiffLines,
+    });
+  } catch (e) {
+    console.error(`❌ ${e.message}`);
+    process.exit(1);
+  }
+
+  // 关单范围对账（2026-11-11）：打印「文档外实际改动」清单——advisory 恒 exit 0，与 --strict 互不干扰；
+  // 供 closeout 序列 §1 验证节调用（口径：非空先解释或回填 plan 再关单）。
+  if (args.scopeReport) {
+    const x = model.steps.find((s) => s.id === 'X' && s.source === 'git');
+    const rows = (x ? x.files : []).map((p) => {
+      const f = model.files.find((g) => g.path === p) || {};
+      return `  - ${p} · ${f.badge || f.status || '修改'} · +${f.additions || 0}/-${f.deletions || 0}`;
+    });
+    if (!rows.length) console.log('文档外实际改动：无');
+    else {
+      console.log(`文档外实际改动：${rows.length} 处（先解释或回填 plan 再关单）`);
+      for (const line of rows) console.log(line);
+    }
+    return;
+  }
+
+  // 解析健康度（2026-11-09）：文档标题跑偏时静默降级的可观测面；--strict 时层兜底/无步骤直接拒产
+  // （exit 1），默认 advisory 只提示。2026-11-10 修正：拒产判定先于 --json 出口——
+  // --json --strict 组合下拒绝产出且不输出模型，解析正常时 --json 行为不变。
+  const ph = model.parseHealth || {};
+  if (args.strict && (ph.layersFallback || !ph.total)) {
+    console.error('❌ --strict：解析命中不达标（层兜底或无步骤），拒绝产出');
+    process.exit(1);
+  }
+
+  // 每步文件门（2026-11-11）：实现步骤必须有「- 文件：」条目，否则全景图只能把文件归到附录。
+  // 纯验证步骤（单测 / UI 实测 / 静态门）天然没有代码文件，按标题豁免；A/U 是归集步，不参与。
+  const VERIFY_STEP_RE = /(单测|集成测试|测试收口|冒烟|UI 实测|静态门|门禁|验证步骤)/;
+  const zeroImpl = model.steps.filter((s) => s.id !== 'A' && s.id !== 'U' && !(s.files || []).length && !VERIFY_STEP_RE.test(s.title || ''));
+  if (zeroImpl.length) {
+    const names = zeroImpl.map((s) => `${s.id} ${String(s.title).split('：')[0]}`).join('、');
+    if (args.strict) {
+      console.error(`❌ --strict：${zeroImpl.length} 个实现步骤没有文件条目（${names}）——在任务下补「- 文件：路径」，纯验证步骤请在标题写明「验证步骤」`);
+      process.exit(1);
+    }
+    console.error(`   ⚠ ${zeroImpl.length} 个实现步骤没有文件条目（${names}）——建议在任务下补「- 文件：…」`);
+  }
+
+  if (args.json) { console.log(JSON.stringify(model, null, 2)); return; }
+  const bs = ph.bySource || {};
+  console.log(`   解析命中：直认 ${ph.direct ?? '?'}/${ph.total ?? '?'} 步` +
+    (bs.blocks ? ` · 改动块归集 ${bs.blocks}` : '') +
+    (bs.layers ? ` · 层兜底 ${bs.layers}` : '') +
+    (bs.fallback ? ` · 未分步 ${bs.fallback}` : '') +
+    (ph.pathGuesses && ph.pathGuesses.total ? ` · 路径猜测 ${ph.pathGuesses.total} 处` : '') +
+    (ph.zeroFileSteps ? ` · 无文件步骤 ${ph.zeroFileSteps}` : '') +
+    (model.deps && model.deps.edges.length ? ` · 依赖边 ${model.deps.edges.length}` : ''));
+  if (model.deps && model.deps.unresolved) {
+    console.error(`   ⚠ 依赖子句有 ${model.deps.unresolved} 处引用未解析到步骤（检查执行顺序节编号与任务编号是否一致）`);
+  }
+  if (ph.layersFallback) {
+    console.error('   ⚠ 步骤未被结构化识别（走了架构层兜底）——规范 `## 任务拆解` / `## 改动方案` 标题后重生成更准');
+  }
+  // 解析失约定位（2026-11-10）：issues 逐条到行，advisory——不参与 --strict 拒产判定。
+  const ISSUE_LABEL = {
+    'step-no-files': '步骤无对齐文件块（改动方案缺该步的文件条目）',
+    'block-unmatched': '文件块锚点未对齐任何步骤（编号/标题与任务拆解不一致）',
+    'dep-unresolved': '依赖引用未解析到步骤（编号与步骤序号/Tn 不一致）',
+    'layers-fallback': '全文无结构化步骤标题，按架构层兜底分组',
+  };
+  for (const it of (ph.issues || [])) {
+    console.error(`   ⚠ 第 ${it.line} 行：${it.title}：${ISSUE_LABEL[it.kind] || it.kind}`);
+  }
+
+  const tpl = fs.readFileSync(TEMPLATE, 'utf8');
+  if (!tpl.includes('__TOUR_DATA__')) {
+    console.error('❌ 模板缺少 __TOUR_DATA__ 锚点');
+    process.exit(1);
+  }
+  const html = tpl
+    .replace('__TOUR_DATA__', escJsonForScript(model))
+    .replace('__TOUR_FILE__', 'null')
+    .replace('__TOUR_MODE__', '"snapshot"');
+
+  const outPath = path.resolve(ROOT, args.out || defaultOut(model.doc.path, model));
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, html, 'utf8');
+
+  const docs = model.files.filter((f) => f.layer === 'doc').length;
+  console.log(`✅ 开发全景已生成：${path.relative(ROOT, outPath)}`);
+  console.log(`   文档：${model.doc.type} · ${model.doc.title}`);
+  console.log(`   范围：${model.steps.length} 步 · ${model.stats.files} 个产品文件` +
+    `（新增 ${model.stats.new} / 修改 ${model.stats.modified} / 删除 ${model.stats.deleted} / 计划 ${model.stats.planned}）` +
+    ` · +${model.stats.additions}/-${model.stats.deletions} 行` + (docs ? ` · ${docs} 个文档` : ''));
+  if (model.note) console.log(`   ⚠ ${model.note}`);
+  if (model.base.note) console.log(`   ⚠ git 基线 ${model.base.ref}：${model.base.note}`);
+  console.log(`   打开快照：file://${outPath.replace(/\\/g, '/')}`);
+  console.log(`   实时版：node .agents/scripts/ensure-board.mjs 后访问 /tour?file=${encodeURI(model.doc.path)}`);
+}
+
+main();

package/templates/engine/.agents/scripts/gen-effective-policy.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// gen-effective-policy.mjs — 当前生效规则视图生成器（2026-10-09 AI-Native 架构审查 P2-5）
+// 背景：豁免锚经 policy v1→v8 演进后，「存量豁免 vs 受管」的合成语义只活在 check-loop.mjs 源码里，
+//   规则空间永久二分且不可读——本脚本把 policy.mjs 单源渲染为人可读的 workflow/effective-policy.md，
+//   与 INDEX.md 同款「生成物 + --check 防漂移」纪律；verify.mjs 挂 --check 门（CI 强制随 policy 变更重生成）。
+// 渲染内容：当前生效 policyVersion（engine.json，缺省回落 v1）、逐锚键的生效日 / 消费检查项 / 分级现状
+//   （hard·已生效 / advisory·已生效 / 未到期——锚日 > 今日的升级锚标注「待升级」；
+//   执法段已退役的锚标注「执法已退役」，不宣称不存在的执法——2026-10-28 引擎减重 hygiene 16 段全退）。
+// 判定单源：锚定义 = policy.mjs POLICIES（本脚本不写日期，只读只渲染）；键→检查项映射取自
+//   check-loop.mjs 头部检查清单（编号是文档引用锚，此处仅作说明文本）。
+// 用法：node .agents/scripts/gen-effective-policy.mjs [--root <dir>] [--check]
+//   --check：与磁盘 workflow/effective-policy.md 比对，漂移 exit 1（CI/verify 用）。
+//   比对前双侧行尾归一（CRLF→LF）。生成器仍只写 LF，--check 不改文件。
+//   干净的 autocrlf 检出是 CRLF，字节相等会假红，且重生成只留下不可提交的行尾差。
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { POLICIES, loadKitPolicy } from './policy.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const ROOT = argOf('--root') || path.resolve(SCRIPT_DIR, '..', '..');
+const OUT = path.join(ROOT, 'workflow', 'effective-policy.md');
+
+// 键 → 消费检查项与分级说明（单源 check-loop 检查清单编号；说明文本与本脚本共同演进）。
+// 分级 RETIRED_LEVEL = 执法段已退役（编号留疤引用不重排）：行仍列出（policy 锚单源存档），
+// 但消费检查项显式标注退役日期、现状不再渲染「已生效」——生成物不得宣称不存在的执法。
+const RETIRED_LEVEL = '已退役';
+const CONSUMERS = {
+  moduleSince: ['检查 12（已于 2026-10-28 退役）', 'frontmatter「模块:」枚举合法性（§12 并入 §9 后随 hygiene 段退役）', RETIRED_LEVEL],
+  check14Since: ['检查 14（已于 2026-10-28 退役）', '新 done 的 spec/plan 须有 approved git 历史——advisory 生效锚', RETIRED_LEVEL],
+  check14HardSince: ['检查 14（已于 2026-10-28 退役）', '同上——锚日起升 hard-block', RETIRED_LEVEL],
+  confirmDocsEffective: ['检查 15', 'docs 确认台账两条件准入（台账行 ∪ 自报日期≥锚）', 'hard'],
+  confirmIncidentsEffective: ['检查 15', 'incidents 档确认阈值（fixed/closed 配对）', 'hard'],
+  bindingTs: ['检查 15', '四终态内容绑定（台账行 ts≥锚 才比对 sha256）', 'hard'],
+  delegationSince: ['检查 18（已于 2026-10-28 退役）', '委派台账对账——锚前存量豁免', RETIRED_LEVEL],
+  stageGateSince: ['检查 19（已于 2026-10-28 退役）', '逐阶段审计（起草先于入口确认 / 台账顺序）', RETIRED_LEVEL],
+  check17UnclosedAfter: ['检查 17（已于 2026-10-21 退役）', '发版提交树未收口三件套——版本 tag 锚（非日期）', RETIRED_LEVEL],
+  verifySince: ['检查 8', '测试绿声明对账（无 SHA 声明「测试绿」须 24h 内凭证）+ confirm-doc →done 前置', 'advisory'],
+  verifyHardSince: ['confirm-doc', '→done 测试绿凭证——锚日起升 hard（拒无凭证关单）', 'hard'],
+  incidentRegrSince: ['检查 3x', '防复发验证证据门（fixed/closed 须落自动化用例/回归清单引用）', 'hard'],
+  specVerifSince: ['检查 21（已于 2026-10-28 退役）', 'spec 验证落地核查（L2/L3 done 的验证计划须引用测试文件/命令）', RETIRED_LEVEL],
+  attributionSince: ['检查 24（已于 2026-10-28 退役）', 'incident 归因字段（来源/影响环境 枚举存在性与合法性）——锚前存量豁免', RETIRED_LEVEL],
+  convergenceSince: ['检查 23', '判据级收敛对账（L2/L3 done spec 验收判据表逐条对证据——完成声明不是证据）——锚前存量豁免', 'advisory'],
+  convergenceHardSince: ['检查 23', '同上——证据无效升 hard（命令须有不早于 spec 日期的 verify-evidence 全绿行；路径只认存在）', 'hard'],
+  reviewerSince: ['检查 1', '独立复核上下文标识（复核行须含「复核上下文：<会话/子代理 id>」——独立性声明可证伪化）——锚前存量豁免', 'advisory'],
+  clarifySince: ['confirm-doc（stage-gates clarifyGate）', 'spec 确认门歧义清单门——锚起新建 spec 须过 6 维 × 状态闭集 × 待澄清归零（缺维 = 未扫描）', 'hard'],
+  coverageSince: ['confirm-doc（stage-gates coverageGate）', 'spec 确认门验收覆盖门——intent 验收编号 A1..An 每条至少被 spec 判据表「对应验收」列引用一次（单向）', 'hard'],
+  premiseSince: ['confirm-doc（stage-gates premiseGate）', 'spec 确认门前提质询门——锚起新建 spec 须有非空且非占位的「前提质询」表（拦「自信的错误解读」进事实源；无解读风险写「无关键前提」行 + 理由）', 'hard'],
+  regrEnforcerSince: ['检查 29', '回归清单执法者配对——锚起数据行「执法者」列须非空（真执法资产或显式 [prompt-only]）——锚前存量不追溯', 'hard'],
+};
+
+// today：视图基准日。EFFECTIVE_POLICY_TODAY 为测试注入缝（场景 2f 跨锚日稳定性用；生产不设）。
+const today = () => process.env.EFFECTIVE_POLICY_TODAY || new Date().toISOString().slice(0, 10);
+
+function render(viewDateStr) {
+  const policy = loadKitPolicy(ROOT);
+  const v = POLICIES[policy.policyVersion] || {};
+  const todayStr = viewDateStr || today();
+  const lines = [];
+  lines.push('# 当前生效规则视图（生成物，勿手改）');
+  lines.push('');
+  lines.push('> 生成器 `node .agents/scripts/gen-effective-policy.mjs`（policy.mjs 单源渲染；漂移由 verify.mjs `effective-policy` 门 --check 把关——改 policy 后须重生成并随同提交）。');
+  lines.push(`> 当前生效：**policyVersion ${policy.policyVersion}**（engine.json 声明 ${policy.requestedVersion}${policy.requestedVersion === policy.policyVersion ? '' : '，不在 POLICIES 表内已回落 v1'}）；视图日期 ${todayStr}。`);
+  lines.push('');
+  lines.push('| 锚键 | 生效日/锚 | 消费检查项 | 语义 | 分级 | 现状 |');
+  lines.push('|---|---|---|---|---|---|');
+  for (const key of Object.keys(v)) {
+    const raw = v[key];
+    const c = CONSUMERS[key] || ['—', '（未登记消费方——policy 加新键时同步登 CONSUMERS）', '—'];
+    const isDate = /^\d{4}-\d{2}-\d{2}$/.test(String(raw));
+    // 升级锚语义：日期 > 今日 = 未到期（维持低档）；其余 = 已生效；
+    // 执法段已退役的锚不按日期宣称执法（编号留疤，锚仅存档）。
+    const status = c[2] === RETIRED_LEVEL
+      ? '执法已退役（锚存档）'
+      : (!isDate ? '生效（版本锚）' : (String(raw) <= todayStr ? '已生效' : `待升级（${raw} 起）`));
+    lines.push(`| \`${key}\` | ${raw} | ${c[0]} | ${c[1]} | ${c[2]} | ${status} |`);
+  }
+  lines.push('');
+  lines.push('<!-- GENERATED:BEGIN — gen-effective-policy.mjs 整段重写，手工说明写在本行之前 -->');
+  return lines.join('\n') + '\n';
+}
+
+const text = render();
+// 行尾归一（与 gen-workflow-index.mjs normEol 同句）：只影响 --check 判定，写盘仍是 LF。
+const normEol = (s) => String(s).replace(/\r\n/g, '\n');
+if (argv.includes('--check')) {
+  let disk = '';
+  try {
+    disk = fs.readFileSync(OUT, 'utf8');
+  } catch { /* 缺文件视作空——走漂移分支 */ }
+  // 锚日时间炸弹拆除（2026-10-12 CI 实证：v12 两锚定 10-12，10-11 生成的视图含「待升级（10-12 起）」，
+  // 锚日当天重渲染按当日判「已生效」→ 与仓内视图必差 → --check 必红——任何未来日期锚都会在锚日引爆）。
+  // 修法：--check 对**磁盘文件自带的视图日期**重渲染（生成物与自身生成日自洽，跨锚日字节稳定）；
+  // 显式重生成（默认模式）才前进视图日期并翻转状态列。视图日期行缺失的存量件回落当日口径。
+  const mDate = disk.match(/视图日期 (\d{4}-\d{2}-\d{2})/);
+  const checkText = mDate ? render(mDate[1]) : text;
+  if (normEol(disk) === normEol(checkText)) {
+    console.log('[effective-policy] ✅ 与磁盘一致（无漂移；按磁盘视图日期重渲染比对）');
+    process.exit(0);
+  }
+  console.error('[effective-policy] ❌ 漂移：policy/engine 变更后未重生成 workflow/effective-policy.md');
+  console.error('  修法：node .agents/scripts/gen-effective-policy.mjs && git add workflow/effective-policy.md（随 policy 变更同笔提交）');
+  process.exit(1);
+}
+fs.mkdirSync(path.dirname(OUT), { recursive: true });
+fs.writeFileSync(OUT, text);
+console.log(`✅ 已生成 ${path.relative(process.cwd(), OUT)}`);