agentic-flow-kit 1.8.7 → 2.0.0

package/modules/hosts/trae/rules/project-workflow.md

@@ -1,14 +0,0 @@
----
-alwaysApply: true
----
-
-本项目工作流唯一权威是根目录 `AGENTS.md`：开工前必须完整读取并严格遵循（任务流程 / 通用约束与红线 / 目录级规则 / 运行时与验证标准），本规则只做入口指针，不复制内容。
-
-- 规则加载是惰性的：根 `AGENTS.md` 常驻；目录级 `AGENTS.md`（如有，如 `backend/AGENTS.md`、`frontend/AGENTS.md`）只在该目录文件被读取或被提及时才生效——动对应目录前先主动读，别凭记忆。
-- 终端环境差异（shell 可用性 / 退出码取法 /「命令不存在 ⇒ 假绿」）见 `.agents/notes/runtime-env.md` §1。
-- 闭环流程目录：`workflow/`（intents / specs / plans / incidents / delegations.md 委派台账 / papercuts.md 留痕）。
-- 6 阶段命令：按用户触发短语路由到 `.trae/commands/wf-*.md`（new-task / plan / design / build / test / deploy / maintain / review）。
-- 子智能体（`.trae/agents/*.md`）按适配器委派；Trae 子智能体为 Beta 功能、需在设置中开启，未开启时按权威命令的 fallback 执行——`fallback: new-session` 必须另开新会话，不得由原会话自查冒充。
-- 闭环兜底以 `.githooks/` 为准（门禁清单以各 hook / `.agents/scripts/check-loop.sh` 头部注释为准，不在本文件复述）；`.trae/hooks/` 在命令执行前再拦一次，`core.hooksPath` 漏配时它是唯一门禁。
-- 委派完成后在 `workflow/delegations.md` 追加一行留痕；命令 / 技能卡壳误导时在 `workflow/papercuts.md` 记一行，不当场顺手改。
-- 中文为项目唯一语言；提交遵循 Conventional Commits 中文。

package/modules/hosts/zcode/agents/implementer.md

@@ -1,51 +0,0 @@
----
-name: implementer
-description: 在已批准且边界明确的工作包内实现改动或补测试；超出授权文件范围即停
----
-# Implementer
-
-> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（各宿主目录下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
-
-## 1. 职责
-
-执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：
-
-- 单文件或边界清晰的局部实现
-- 有明确复现路径的 bug 修复
-- 编写或调整任务直接要求的测试
-- 修复与任务直接相关的编译错误
-
-## 2. 必需输入
-
-开始前必须获得：
-
-- 一句话任务目标
-- 必须读取的入口文档、spec 或 plan
-- 允许修改的文件清单
-- 可执行的验收条件
-
-任一输入缺失或相互冲突时，停止并向主智能体报告，不自行扩大范围。
-
-## 3. 行为边界
-
-- 只修改明确授权的文件；若必须触及其他文件，先停止并说明原因。
-- 仓库可能有其他智能体或用户同时工作；保留现有改动，不回退、不覆盖无关修改。
-- 复用现有实现、标准库和已安装依赖，保持最小工作 diff。
-- 不修改公共接口、数据 Schema、依赖、构建步骤、安全或权限策略。
-- 不执行提交、推送、发布、数据迁移或破坏性操作。
-- 不顺手重构、格式化或清理与任务无关的代码。
-
-## 4. 验证
-
-- 运行任务指定的最小相关检查。
-- 检查失败时只修复由本次改动引起且仍在授权范围内的问题。
-- 同一验证连续失败三次，或继续需要猜测需求时，停止并报告阻塞。
-
-## 5. 输出
-
-返回给主智能体：
-
-1. 修改文件清单
-2. 每个文件的改动摘要
-3. 已运行的验证及结果
-4. 未解决的阻塞或剩余风险

package/modules/hosts/zcode/agents/independent-reviewer.md

@@ -1,49 +0,0 @@
----
-name: independent-reviewer
-description: 只读独立复核（spec 或实现 diff）；不改动文件、不替用户批准
----
-# Independent Reviewer
-
-> 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主薄适配（各宿主目录下 `agents/independent-reviewer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
-
-## 1. 职责
-
-在独立上下文中对 spec、plan 或代码 diff 做只读复核，发现原作者可能遗漏的正确性、契约、架构、数据安全和回归风险。
-
-## 2. 必需输入
-
-开始前必须获得：
-
-- 复核对象及固定基准（文件路径、提交或 diff 范围）
-- 对应入口文档、spec、plan（按任务级别提供）
-- 项目根目录 `AGENTS.md` + 改动域对应的目录级 `AGENTS.md`（如有）
-- 期望的复核结论或验收标准
-
-输入不足以确定范围时，停止并向主智能体报告。
-
-## 3. 行为边界
-
-- 只读，不修改任何仓库文件。
-- 不替用户决定问题定性、方案取舍、合入或上线。
-- 不继承或猜测原作者未写入输入材料的推理。
-- 只报告能用具体文件、行号、行为或契约证明的问题。
-- 不把样式偏好、假设性风险或既有无关问题包装成缺陷。
-- 无法验证的事项明确标为未验证，不声称已经通过。
-
-## 4. 复核重点
-
-1. 实现是否满足入口文档和验收标准
-2. 是否违反根 `AGENTS.md` 与改动域目录级 `AGENTS.md` 的架构、数据和所在域红线
-3. 是否改变未批准的公共契约或范围
-4. 是否缺少能防止回归的验证
-5. 是否存在数据丢失、安全、权限或发布风险
-
-## 5. 输出
-
-按严重度输出问题清单：
-
-- `P0`：数据、安全、权限或必然阻断交付的问题
-- `P1`：功能错误、明确回归或违反项目硬约束
-- `P2`：非阻断但有证据的维护性问题
-
-每项必须包含：位置、问题、证据、建议。没有发现时明确输出"未发现阻断问题"，并列出未验证范围。

package/modules/hosts/zcode/agents/ui-verifier.md

@@ -1,48 +0,0 @@
----
-name: ui-verifier
-description: 浏览器实测 UI 改动（只读验证、不留脏数据）；结论按页面/步骤/证据回报
----
-# UI Verifier
-
-> 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（各宿主目录下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
-
-## 1. 职责
-
-对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。
-
-## 2. 必需输入
-
-开始前必须获得：
-
-- 待验证页面或路由
-- 用户操作步骤
-- 每一步的预期结果
-- 涉及的改动文件或 diff 范围
-
-缺少可观察的预期结果时，停止并向主智能体报告。
-
-## 3. 执行
-
-1. 读取项目根目录 `AGENTS.md`，以及改动域目录级 `AGENTS.md`（如有，前端改动域）。
-2. 读取并遵循项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`（如有）。
-3. 启动该技能指定的 API、前端和浏览器验证环境。
-4. 按输入步骤验证页面行为；布局类问题优先使用可重复的 DOM 几何数据。
-5. 收集控制台、网络请求、DOM 数据或截图等证据。
-6. 结束时关闭本次启动的后台进程。
-
-## 4. 行为边界
-
-- 不修改代码、配置、测试数据或工作流文档。
-- 不自行修复发现的问题；将失败证据交还主智能体。
-- 不使用生产环境或真实业务数据。
-- 无法启动环境或完成关键路径时，报告阻塞，不把部分验证标记为通过。
-
-## 5. 输出
-
-返回：
-
-1. 验证环境与页面路由
-2. 逐项通过/失败结果
-3. 失败的复现步骤和证据
-4. 控制台或网络异常
-5. 未验证范围与阻塞项

package/src/add-gate.mjs

@@ -1,116 +0,0 @@
-// flow-kit add-gate <门禁>：装门禁模块到 .agents/hooks/ 并接线 local-pre-commit 挂载点。
-// 模块约定：modules/gates/<gate>/ 下源文件拷入 .agents/hooks/（平铺，README.md 与 local-pre-commit.line 为包内元数据不拷）；
-// local-pre-commit.line 内容 = 需追加进 .agents/hooks/local-pre-commit 的挂载行（存在同名行则不重复追加，幂等）。
-// 门禁装后归项目所有：入 owned 台账，sync 永不覆盖（改红线/删不适用条目自行编辑——见各模块 README）。
-// gate 防改锚（2026-10-11 P3-1）：逐字拷贝安装的 gate 脚本，owned 条目写 srcSha256＝安装时刻包源文件
-// （modules/gates/<gate>/<file>）的 LF 归一 sha。语义：sync 对 owned 的 sha256 按盘面自愈（记账不约束），
-// 但 srcSha256 只按包源刷新——gate 文件在装户 sync 中 srcTemplatePath 解析不到包源模板（templates/_agents/
-// hooks/ 无同名件）即提前 return，锚一经写入恒定。doctor 的 gate 安装锚校验据此让「装后手改」永久可见：
-// 装户可改（不阻断），但改了会被看见。--force 重装锚随新安装刷新（即重锚路径）；已存在被跳过的文件锚
-// 盘面现状（盘面非逐字拷贝，锚包源会装后即误报），盘面与包源不一致时 WARN 差异。local-pre-commit 是
-// 合并接线件（模板 + 各门挂载行），非逐字拷贝——不写锚（它的 srcSha256 由 init/sync 按模板语义记，含义不同）。
-import fs from 'node:fs';
-import path from 'node:path';
-import { sha256 } from './render.mjs';
-
-function fail(msg) {
-  console.error(`❌ ${msg}`);
-  process.exit(1);
-}
-
-const META = new Set(['README.md', 'local-pre-commit.line']); // 包内文档/接线元数据，不装进项目
-
-export function addGate(args, pkgRoot) {
-  const gatesRoot = path.join(pkgRoot, 'modules', 'gates');
-  const available = fs.existsSync(gatesRoot) ? fs.readdirSync(gatesRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
-  const gate = args[0];
-  if (!gate || gate.startsWith('--')) fail(`缺少门禁参数（可选：${available.join(' | ') || '无'}）`);
-  if (!available.includes(gate)) fail(`未知门禁：${gate}（可选：${available.join(' | ') || '无'}）`);
-
-  let target = process.cwd();
-  let force = false;
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--dir') target = path.resolve(args[++i] || fail('--dir 缺少值'));
-    else if (args[i] === '--force') force = true;
-    else fail(`未知选项：${args[i]}`);
-  }
-
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init`);
-  const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-
-  const srcRoot = path.join(gatesRoot, gate);
-  const hooksDir = path.join(target, '.agents', 'hooks');
-  fs.mkdirSync(hooksDir, { recursive: true });
-  console.log(`▶ flow-kit add-gate ${gate} → ${target}`);
-
-  const installed = [], skipped = [];
-  let wireLine = null;
-  for (const entry of fs.readdirSync(srcRoot, { withFileTypes: true })) {
-    if (entry.isDirectory()) fail(`门禁模块含子目录（${entry.name}）——平铺约定不支持，请检查模块内容`);
-    if (entry.name === 'local-pre-commit.line') { wireLine = fs.readFileSync(path.join(srcRoot, entry.name), 'utf8').trim(); continue; }
-    if (META.has(entry.name)) continue;
-    const dst = path.join(hooksDir, entry.name);
-    if (fs.existsSync(dst) && !force) { skipped.push(entry.name); continue; }
-    fs.copyFileSync(path.join(srcRoot, entry.name), dst);
-    installed.push(entry.name);
-  }
-  console.log(installed.length ? `  安装到 .agents/hooks/：${installed.join('、')}` : '  无新文件');
-  if (skipped.length) console.log(`  跳过（已存在，--force 覆盖）：${skipped.join('、')}`);
-
-  // 接线 local-pre-commit（幂等：挂载行已存在不重复；旧装态尾部 exit 0 会吞掉其后门禁的失败——归一化剥掉）
-  let wiredLp = false;
-  if (wireLine) {
-    const lpPath = path.join(hooksDir, 'local-pre-commit');
-    const cur = fs.existsSync(lpPath) ? fs.readFileSync(lpPath, 'utf8') : '';
-    if (cur.split(/\r?\n/).some((l) => l.trim() === wireLine)) {
-      console.log('  local-pre-commit 已接线（幂等跳过）');
-    } else {
-      let lines = cur.split(/\r?\n/);
-      while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
-      if (lines.length && lines[lines.length - 1].trim() === 'exit 0') {
-        lines.pop();
-        console.log('  local-pre-commit 归一化：剥掉尾部 exit 0（旧装态，会吞掉其后门禁的失败）');
-      }
-      const body = lines.length ? `${lines.join('\n')}\n` : '#!/bin/sh\nset -e\n';
-      fs.writeFileSync(lpPath, `${body}${wireLine}\n`);
-      console.log(`  local-pre-commit 接线：+ ${wireLine}`);
-      wiredLp = true;
-    }
-  }
-
-  // owned 台账补记（归项目所有，sync 永不覆盖）。接线改写了 local-pre-commit（init 时按模板态记账）——
-  // 须同步刷新其 owned 哈希，否则台账停在模板态（Shipyard 回流发现的漂移根因，2026-09-24）。
-  // 记账一律 LF 归一（init-p1-batch P1-4 rider）：与 doctor §6.6 / sync ownedSha 同口径，跨 checkout 字节稳定
-  const shaText = (p) => sha256(Buffer.from(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
-  const ownedLedger = new Map((kit.owned || []).map((f) => [f.rel, f]));
-  // 跳过件（盘上已存在、未 --force）：先出声再记账——盘面与包源不一致即本地已改，WARN 保证差异在安装输出可见。
-  // 无台账条目的首次见面按盘面现状建立基线与锚；已有条目则原样保留（锚停在安装时刻值，盘面手改
-  // 继续由 doctor gate 安装锚校验留痕——重锚会把手改吸收成「无差异」，违背防改锚初衷）。
-  for (const name of skipped) {
-    const rel = `.agents/hooks/${name}`;
-    const known = ownedLedger.has(rel);
-    if (shaText(path.join(hooksDir, name)) !== shaText(path.join(srcRoot, name))) {
-      console.log(known
-        ? `  ⚠️ ${name} 盘面与包源不一致（本地已改）——原锚保留，手改由 doctor 锚校验留痕；重装覆盖用 --force`
-        : `  ⚠️ ${name} 盘面与包源不一致（本地已改），锚记盘面现状——重装覆盖用 --force`);
-    }
-    if (!known) {
-      const diskSha = shaText(path.join(hooksDir, name));
-      ownedLedger.set(rel, { rel, sha256: diskSha, srcSha256: diskSha });
-    }
-  }
-  for (const name of installed) {
-    const rel = `.agents/hooks/${name}`;
-    // srcSha256＝安装时刻包源文件 sha（gate 防改锚，见文件头注）：sha256 被 sync 按盘面自愈，锚恒定
-    ownedLedger.set(rel, { rel, sha256: shaText(path.join(hooksDir, name)), srcSha256: shaText(path.join(srcRoot, name)) });
-  }
-  if (wiredLp) {
-    const lpRel = '.agents/hooks/local-pre-commit';
-    ownedLedger.set(lpRel, { rel: lpRel, sha256: shaText(path.join(hooksDir, 'local-pre-commit')) });
-  }
-  kit.owned = [...ownedLedger.values()].sort((a, b) => a.rel.localeCompare(b.rel));
-  fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
-
-  console.log('✅ 门禁已装（归项目所有，sync 不覆盖）。装后首个 commit 前先核对脚本头部 CONFIG 的目录/类型名——门禁 fail-closed，目标缺失会拦截提交。');
-}

package/src/add-gate.test.mjs

@@ -1,103 +0,0 @@
-#!/usr/bin/env node
-// add-gate.test.mjs — gate 防改锚（2026-10-11 P3-1）装户端到端测试。
-// 手法：真实 bin/flow-kit.mjs init 建临时装户（fresh-init.test.mjs 同款）→ CLI add-gate test-protect，
-// 断言 kit.json owned：逐字拷贝的 gate 脚本带 srcSha256＝安装时刻包源文件 LF 归一 sha；
-// local-pre-commit（合并接线件，非逐字拷贝）不写 srcSha256。再覆盖三条锚路径——
-//   ①幂等重跑（盘面＝包源）安静且锚不动；②盘面手改后重跑（未 --force）WARN 差异 + 原锚保留
-//   （doctor checkGateAnchors 端到端抓到手改）；③--force 重装重锚。
-// 用法：node src/add-gate.test.mjs
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const CLI = path.join(ROOT, 'bin', 'flow-kit.mjs');
-const GATE = 'test-protect';
-const GATE_REL = `.agents/hooks/check-test-protect.mjs`;
-const LP_REL = '.agents/hooks/local-pre-commit';
-const PKG_GATE_SRC = path.join(ROOT, 'modules', 'gates', GATE, 'check-test-protect.mjs');
-
-// checkGateAnchors 端到端联动：add-gate 写下的锚正是 doctor 锚校验读取的判据（耦合面单独断言）
-const { checkGateAnchors } = await import(pathToFileURL(path.join(ROOT, 'src', 'doctor.mjs')).href);
-
-let pass = 0;
-let fail = 0;
-const check = (name, cond, detail = '') => {
-  if (cond) { pass++; console.log(`PASS  ${name}`); }
-  else { fail++; console.log(`FAIL  ${name}${detail ? `\n      ${detail}` : ''}`); }
-};
-// LF 归一 sha（与 add-gate shaText / doctor checkGateAnchors 同口径，跨 checkout 字节稳定）
-const shaOf = (p) => createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-const R = (p) => fs.readFileSync(p, 'utf8');
-
-// ---- 建临时装户：git init + 真实 CLI init（fresh-init.test.mjs 同款）----
-const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-addgate-'));
-spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', ['init', '-q'], { cwd: dir });
-const init = spawnSync(process.execPath, [CLI, 'init', '--stack', 'none', '--hosts', 'claude', '--board-port', '8941', '--dir', dir], { encoding: 'utf8', timeout: 120000 });
-if (init.status !== 0) {
-  console.error(`add-gate.test.mjs：前置 init 失败无法继续\n${(init.stdout || '') + (init.stderr || '')}`);
-  process.exit(1);
-}
-const kitOf = () => JSON.parse(R(path.join(dir, '.agents', 'kit.json')));
-const gateEntry = () => kitOf().owned.find((f) => f.rel === GATE_REL);
-
-// ---- 场景 1：首装——逐字拷贝件写锚＝包源 sha；local-pre-commit 不写锚 ----
-{
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  check('S1 add-gate exit 0', r.status === 0, `exit=${r.status}\n${out.slice(-400)}`);
-  const gate = gateEntry();
-  check('S1 gate 脚本带 srcSha256＝包源文件 LF 归一 sha（安装时刻包源）', !!gate && gate.srcSha256 === shaOf(PKG_GATE_SRC), JSON.stringify(gate || null));
-  check('S1 gate 台账 sha256＝盘面（LF 归一记账）', !!gate && gate.sha256 === shaOf(path.join(dir, GATE_REL)), JSON.stringify(gate || null));
-  check('S1 门禁脚本落盘且与包源一致（逐字拷贝）', R(path.join(dir, GATE_REL)) === R(PKG_GATE_SRC));
-  const lp = kitOf().owned.find((f) => f.rel === LP_REL);
-  check('S1 local-pre-commit（合并接线件）不写 srcSha256', !!lp && lp.srcSha256 === undefined, JSON.stringify(lp || null));
-  check('S1 local-pre-commit 台账 sha256 刷为接线后盘面', !!lp && lp.sha256 === shaOf(path.join(dir, LP_REL)), JSON.stringify(lp || null));
-  check('S1 首装输出无盘面/包源差异 WARN', !out.includes('盘面与包源不一致'), out);
-}
-
-// ---- 场景 2：幂等重跑（未 --force、盘面＝包源）——安静，条目原样 ----
-{
-  const before = JSON.stringify(gateEntry());
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  check('S2 幂等重跑 exit 0 且无差异 WARN', r.status === 0 && !out.includes('盘面与包源不一致'), out);
-  check('S2 锚与台账条目原样', JSON.stringify(gateEntry()) === before, `${before} → ${JSON.stringify(gateEntry())}`);
-}
-
-// ---- 场景 3：盘面手改后重跑（未 --force）——WARN 差异可见，原锚保留（手改永久留痕）----
-{
-  fs.writeFileSync(path.join(dir, GATE_REL), `${R(PKG_GATE_SRC)}\n// 本地手改：放宽红线（测试标记）\n`);
-  const before = gateEntry();
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  const after = gateEntry();
-  check('S3 手改后重跑出 WARN（盘面与包源不一致，含文件名）', out.includes('盘面与包源不一致') && out.includes('check-test-protect.mjs'), out);
-  check('S3 已有台账条目 → WARN 指明原锚保留', out.includes('原锚保留'), out);
-  check('S3 原锚保留（未被盘面重锚——重锚会把手改吸收成无差异）', after.srcSha256 === before.srcSha256 && after.srcSha256 === shaOf(PKG_GATE_SRC), `${JSON.stringify(before)} → ${JSON.stringify(after)}`);
-  check('S3 台账 sha256 亦不被改写（未 --force 不动既有条目）', after.sha256 === before.sha256, `${JSON.stringify(before)} → ${JSON.stringify(after)}`);
-  check('S3 手改盘面幸存（未 --force 不覆盖）', R(path.join(dir, GATE_REL)).includes('本地手改'), R(path.join(dir, GATE_REL)).slice(-120));
-  const d = checkGateAnchors(dir);
-  check('S3 doctor 锚校验按 add-gate 写下的锚抓到手改（端到端）', d.skipped === false && d.mismatch.includes(GATE_REL), JSON.stringify(d));
-}
-
-// ---- 场景 4：--force 重装——盘面恢复包源 + 锚随新安装刷新（重锚路径）----
-{
-  const r = spawnSync(process.execPath, [CLI, 'add-gate', GATE, '--dir', dir, '--force'], { encoding: 'utf8' });
-  const out = r.stdout + r.stderr;
-  const gate = gateEntry();
-  check('S4 --force 重装恢复包源内容', R(path.join(dir, GATE_REL)) === R(PKG_GATE_SRC));
-  check('S4 锚随新安装刷新（srcSha256＝包源 sha）', !!gate && gate.srcSha256 === shaOf(PKG_GATE_SRC), JSON.stringify(gate || null));
-  check('S4 台账 sha256 回到包面值', !!gate && gate.sha256 === shaOf(PKG_GATE_SRC), JSON.stringify(gate || null));
-  check('S4 输出含安装报告', out.includes('安装到'), out);
-  const d = checkGateAnchors(dir);
-  check('S4 重锚后 doctor 锚校验回到无失配', d.skipped === false && d.mismatch.length === 0 && d.gone.length === 0 && d.total >= 1, JSON.stringify(d));
-}
-
-fs.rmSync(dir, { recursive: true, force: true });
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);

package/src/add-host.mjs

@@ -1,68 +0,0 @@
-// flow-kit add-host <宿主>：init 后补装宿主适配层。
-// 渲染 modules/hosts/<h> → HOSTS[h].dir → managed 台账按 rel 去重补记 → options.hosts 补记
-// → localOnly 宿主（2026-10-05 起暂无命中，见 profiles.mjs#HOSTS.localOnly）.gitignore 追加 → doctor
-import fs from 'node:fs';
-import path from 'node:path';
-import { renderTree } from './render.mjs';
-import { HOSTS, pickStackVars } from './profiles.mjs';
-import { doctor } from './doctor.mjs';
-
-function fail(msg) {
-  console.error(`❌ ${msg}`);
-  process.exit(1);
-}
-
-export function addHost(args, pkgRoot) {
-  const host = args[0];
-  if (!host || host.startsWith('--')) fail(`缺少宿主参数（可选 ${Object.keys(HOSTS).join(' | ')}）`);
-  if (!HOSTS[host]) fail(`未知宿主：${host}（可选 ${Object.keys(HOSTS).join(' | ')}）`);
-
-  let target = process.cwd();
-  let force = false;
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--dir') target = path.resolve(args[++i] || fail('--dir 缺少值'));
-    else if (args[i] === '--force') force = true;
-    else fail(`未知选项：${args[i]}`);
-  }
-
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init`);
-  const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-  kit.options = kit.options || {};
-  const already = Array.isArray(kit.options.hosts) && kit.options.hosts.includes(host);
-  if (already && !force) fail(`${host} 已安装（options.hosts 在册）。覆盖更新用 --force`);
-
-  const vars = { BOARD_PORT: String(kit.options.boardPort || '8933'), ...pickStackVars(kit.options.stack) };
-  console.log(`▶ flow-kit add-host ${host} → ${target}${already ? '（--force 覆盖更新）' : ''}`);
-
-  // 宿主层渲染（已存在保守跳过；--force 覆盖）
-  const r = renderTree(path.join(pkgRoot, 'modules', 'hosts', host), path.join(target, HOSTS[host].dir), vars, { force });
-  if (!r.written.length && r.skipped.length) console.log('  跳过（已存在，未覆盖）：' + r.skipped.join('、'));
-  else console.log(`  安装 ${r.written.length} 份${r.skipped.length ? `，跳过已存在 ${r.skipped.length} 份` : ''}`);
-  if (r.skipped.length) {
-    // 跳过的文件不入 managed 台账（不接管既有内容）——后续 sync 只报「已存在未入台账」，永不升级；纳入包管理须 --force
-    console.log('  ⚠️ 跳过文件不入 managed 台账、后续 sync 不升级（每次仅报告）；纳入包管理用 --force 覆盖');
-  }
-
-  // managed 台账按 rel 去重补记
-  const ledger = new Map((kit.managed || []).map((f) => [f.rel, f]));
-  for (const f of r.written) ledger.set(`${HOSTS[host].dir}/${f.rel}`, { rel: `${HOSTS[host].dir}/${f.rel}`, sha256: f.sha256 });
-  kit.managed = [...ledger.values()].sort((a, b) => a.rel.localeCompare(b.rel));
-  if (!already) kit.options.hosts = [...(kit.options.hosts || []), host];
-  fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
-
-  // localOnly 宿主进 .gitignore（缺才补）。2026-10-05 起七个宿主一律 localOnly:false，该分支暂无宿主命中；
-  // 保留是为了未来重开「本机专属宿主」档位时不必改结构——判定单源在 profiles.mjs#HOSTS.localOnly。
-  if (HOSTS[host].localOnly) {
-    const giPath = path.join(target, '.gitignore');
-    const line = `${HOSTS[host].dir}/`;
-    const giText = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
-    if (!giText.split(/\r?\n/).some((x) => x.trim() === line)) {
-      fs.writeFileSync(giPath, (giText.endsWith('\n') || giText === '' ? giText : giText + '\n') + line + '\n');
-      console.log(`  .gitignore 追加：${line}`);
-    }
-  }
-
-  console.log('▶ flow-kit doctor');
-  doctor(['--dir', target], pkgRoot);
-}

package/src/cli.mjs

@@ -1,169 +0,0 @@
-#!/usr/bin/env node
-// flow-kit CLI 入口：init（安装）/ sync（升级）/ add-host（补宿主）/ add-gate（装门禁）/ doctor（体检）/ validate（只读校验）/ sync-hosts（跨宿主同步）/ help
-import { init } from './init.mjs';
-import { doctor } from './doctor.mjs';
-import { validate } from './validate.mjs';
-import { sync } from './sync.mjs';
-import { syncHosts } from './sync-hosts.mjs';
-import { addHost } from './add-host.mjs';
-import { addGate } from './add-gate.mjs';
-import { route, runPipeline, routeKindList } from './executor.mjs';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-
-const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-function gateNames(pkgRoot) {
-  const dir = path.join(pkgRoot, 'modules', 'gates');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name)
-    .sort();
-}
-
-const GATE_LIST = gateNames(PKG_ROOT).join(' | ') || '无';
-
-// route 的 kind 值域从权威面派生（同 GATE_LIST 纪律）：读包源 new-task.md 的 route-kinds 机器单源，
-//   不手写第二份——否则装户改 kind 时本帮助文本与 route 判定面会双源漂移（B5 同一问题）。
-const ROUTE_KIND_LIST = routeKindList(PKG_ROOT).join('|') || 'require|fix|verify|review|deploy';
-
-export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚手架（agentic-flow-kit）
-
-用法：
-  flow-kit init             安装到当前项目（裸跑无参数 → 交互确认环节；带参数直接执行；
-                            已存在的 AGENTS.md 无工作流骨架时文末追加补齐，其余已存在文件保守跳过）
-  flow-kit sync             升级 managed 文件（未改动→覆盖新版；本地已改→跳过并持续报告——台账不基线化，
-                            不会被下次升级静默覆盖；--force 才覆盖；INDEX/看板等生成器目标重跑锚点重写；
-                            owned 文件永不触碰）
-  flow-kit add-host <宿主>  后补宿主适配层：zcode | opencode | trae | omp | claude | cursor | codex
-                            （已存在文件跳过且不入台账，--force 接管）
-  flow-kit add-gate <门禁>  装门禁模块并接线 local-pre-commit（当前：${GATE_LIST}；装后归项目所有）
-  flow-kit sync-hosts       跨宿主适配层同步：templates/_agents/{commands,roles}/*.md 权威源 vs
-                            modules/hosts/<h>/{agents,commands}/*.md 薄适配——默认 --diff 输出报告；
-                            --apply 单向同步（权威→薄适配，不反向避免污染）；
-                            --strict 漂移判红（CI 机器门用；默认 --diff 恒 exit 0，报告器语义）；
-                            改一处权威源要同步 N 份薄适配，人工 grep 易漏
-  flow-kit doctor           体检：目录布局 / git 钩子 / managed 清单 / 索引漂移 / 跨宿主漂移 / check-loop
-  flow-kit validate         只读校验：包内置 check-loop 引擎对装户盘面跑闭环 20 项检查（不执行装户侧脚本，
-                            不改文档台账）；明细走 stderr，stdout 承载汇总——0/1 退出码可作 CI 独立一道门。
-                            与 doctor 的分工：doctor 查「装得健不健康」（含装户侧引擎校验后执行），
-                            validate 查「盘面内容合不合规」（判定引擎随包版本走）
-
-  ── 执行面（引擎执行器：手动路由 + 自动流水线）─────────────────────────
-                            md 指令与 md 子代理仍装在装户项目（.agents/commands、.agents/roles），
-                            宿主读它们；本 CLI 不复制、不改写它们的正文。执行代码亦留在装户
-                            .agents/scripts/，包只做薄壳转发与判定面。
-  flow-kit route            手动路由的机器面：定级（就高不就低 + 路径下限）+ 判据清单 + 泳道 + 下一阶段
-                            + 该读的 md 指令路径。判据单源 = .agents/scripts/level-criteria.mjs；
-                            路径下限清单 = .agents/level-hints.txt（装户自持、内容项目私有，默认空）。
-                            **诚实边界**：级别是意图面的语义判定（「一处定义、多处消费」），机器判不了语义；
-                            未配 hints 时按 L1 起步并提示补配置，绝不假装判得出。
-                            选项：--kind ${ROUTE_KIND_LIST} ｜ --level L1|L2|L3
-                                  --files "a,b"（改动文件，参与路径下限判定）｜ --dir <目录> ｜ --json
-  flow-kit run <子命令>     自动流水线：薄壳转发装户 pipeline-run 状态机
-                            （start / next / status / watch / abort），参数与退出码原样透传。
-                            驱动协议与停机点语义见 .agents/commands/pipeline-run.md（宿主面权威）。
-                            本命令绝不 spawn AI 会话 / 不伪造原话 / 不带 --no-verify。
-
-init 选项（全部可选，均有默认值）：
-  --stack <技术栈>     dotnet | node（ts/js） | python | go | none（默认 none；ts/js/typescript/javascript
-                       归一为 node）——门禁配置三处：commit-check
-                       条件编译检查（builds）与质量检测（checks：lint/类型/vet 等秒级确定性检查，
-                       有对应配置文件才启用）、settings.json 自检验命令权限（allow）、
-                       AGENTS.md「项目适配区」命令预填
-  --hosts <宿主列表>   逗号分隔：zcode,opencode,trae,omp,claude,cursor,codex（默认 zcode；七个宿主一律入库，不自动进 .gitignore）
-  --board-port <端口>  workflow 看板端口（默认 8933）
-  --dir <目录>         目标项目根（默认当前目录）
-  --force              覆盖已存在的同名文件（默认保守跳过）
-
-sync / add-host 选项：--dir <目录>、--force（覆盖本地已改 / 已装内容）；add-gate 选项：--dir <目录>、--force。
-validate 选项：--strict（advisory warning 也判红）/ --json（机器可读，stdout）/ --dir <目录>（目标项目根，默认当前目录）。
-sync-hosts 选项：--diff（默认，仅报告，不修改）/ --apply（单向同步到薄适配）/ --json（机器可读输出）/ --dir <目录>（目标项目根，默认当前目录）。
-sync-hosts 只在包源仓运行（需要 templates/_agents 与 modules/hosts）：比对 templates/_agents ↔ modules/hosts。
-装户的宿主文件由 init / add-host 写入；刷新用 add-host <宿主> --force。
-route 选项：--kind / --level / --files / --dir <目录>（目标项目根，默认当前目录）/ --json（机器可读）。
-run 参数：除 --dir 外原样透传给装户 pipeline-run（--hint / --triage / --delegated / --files / --run / --json / --adopt / --to / --interval）。
-
-示例：
-  npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 确认安装
-  npx agentic-flow-kit init --stack node --hosts zcode,opencode
-  npx agentic-flow-kit sync                        # 包出新版后升级（本地改过的 managed 文件会跳过并报告）
-  npx agentic-flow-kit add-host opencode           # 后补宿主
-  npx agentic-flow-kit add-gate dotnet-ca          # 装 Clean Architecture 门禁
-  npx agentic-flow-kit doctor                       # 体检
-  npx agentic-flow-kit validate --strict            # 只读结构校验（CI 可用，0/1 退出码）
-  npx agentic-flow-kit sync-hosts --diff           # 看权威源 vs 薄适配漂移
-  npx agentic-flow-kit sync-hosts --apply          # 单向同步到薄适配
-  npx agentic-flow-kit route --kind require --level L1 --files "src/a.ts,src/b.ts"
-  npx agentic-flow-kit run start "给导入功能加审计字段"
-  npx agentic-flow-kit run next --delegated "可以"
-
-装完本地可跑：日常闭环走项目内 .agents/scripts/（零 npm 运行时依赖）；升级 / 体检 / 装门禁用 npx agentic-flow-kit（sync / doctor / add-host / add-gate）；AGENTS.md 生成「AI工作流 + Wiki」骨架，项目细节在「项目适配区」自填。`;
-
-// errText：异步命令失败的统一输出。带 code 的错误把 code 一并打出来——
-//   例：flow-kit route 遇非法 level-hints 会抛 e.code = LEVEL_HINTS_INVALID，
-//   只打 message 等于把机器可判的错误类别在 CLI 边界扔掉（路径与行号仍在 message 里）。
-const errText = (e) => `❌ ${e?.code ? `[${e.code}] ` : ''}${e?.message || e}`;
-
-export function run(argv) {
-  const cmd = argv[0];
-  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    console.log(HELP);
-    return;
-  }
-  if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
-    const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
-    console.log(pkg.version);
-    return;
-  }
-  if (cmd === 'init') {
-    init(argv.slice(1), PKG_ROOT).catch((e) => {
-      console.error(errText(e));
-      process.exit(1);
-    });
-    return;
-  }
-  if (cmd === 'sync') {
-    sync(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'sync-hosts') {
-    const code = syncHosts(argv.slice(1), PKG_ROOT);
-    if (typeof code === 'number') process.exit(code);
-    return;
-  }
-  if (cmd === 'add-host') {
-    addHost(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'add-gate') {
-    addGate(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'doctor') {
-    doctor(argv.slice(1), PKG_ROOT);
-    return;
-  }
-  if (cmd === 'validate') {
-    validate(argv.slice(1), PKG_ROOT).catch((e) => {
-      console.error(errText(e));
-      process.exit(1);
-    });
-    return;
-  }
-  if (cmd === 'route') {
-    route(argv.slice(1)).catch((e) => {
-      console.error(errText(e));
-      process.exit(1);
-    });
-    return;
-  }
-  if (cmd === 'run') {
-    runPipeline(argv.slice(1));
-    return;
-  }
-  console.error(`未知命令：${cmd}\n\n${HELP}`);
-  process.exit(1);
-}