agentic-flow-kit 1.4.0 → 1.5.0

package/modules/hosts/trae/commands/wf-maintain.md

@@ -9,11 +9,11 @@ description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1
 
 > 事故回到 Plan。复盘三件套缺一不可,防复发承诺不留在文档里。
 
-## 执行
+## 1. 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；端口 8933 起自动上探，链接以脚本输出为准；不开看板不影响任务流程）。
 
-### 0. 紧急止血(仍在事故中时)
+### 1.1 紧急止血(仍在事故中时)
 
 1. AI 先诊断:读日志 + 代码,给出止血选项(版本回退 / 数据回滚 / 热修 / 降级 / 暂不处理)与各自影响面、耗时
    - **版本回退**(代码 / 配置,无数据影响):回退到上一 `release/<日期>` tag——运行时 / 管线类事故(认证管线 / DI 注册 / 中间件)的首选,须确认上一 tag 可复现构建
@@ -21,13 +21,13 @@ description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1
 2. 止血方案由用户拍板;AI 只执行选定方案,不自行推送修复
 3. 热修代码后仍须补跑 `test.md` 静态门;止血完成再进下面的复盘流程(时间线从本节记起)
 
-### 1. 起草 incident
+### 1.2 起草 incident
 
 1. **先检索同类 incident**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents`——命中同类先读其「根因 / 复盘三件套」，本次三件套须引用其防复发条目（review.md P2 对账项）
 2. 复制 `workflow/incidents/_TEMPLATE.md` → `workflow/incidents/YYYY-MM-DD-<主题>.md`（frontmatter 填 `模块:`，词表见 `.agents/workflow-modules.txt`）
 3. 填 4 节:时间线(发现→定位→止血→恢复,带时刻) / 影响面(页面/接口/数据范围) / 根因(一句话+深层原因) / 为什么之前没拦住(门禁/测试/规范各查一遍)
 
-### 2. 起草复盘三件套(缺一不可)
+### 1.3 起草复盘三件套(缺一不可)
 
 > 目的:让事故真正回到 Plan,不让「防复发」承诺停留在文档里。
 
@@ -49,29 +49,29 @@ description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1
 - 常驻面体积预算由 pre-commit 硬拦(`sh .agents/scripts/rule-budget.sh --staged`,表 `.agents/rule-budgets.txt`)——超限先删再增
 - 引用:commit <SHA> / 文件:<路径>#L<行>;若无新增条目,理由:<已有条目覆盖,说明条目位置>
 
-### 3. 起草后停下
+### 1.4 起草后停下
 
 输出草稿全文给用户过目;确认后才执行三件套落地。**确认点不合并**：incident 草稿、spec、plan 各自过目确认（plan 的两道门见 `build.md`）；确认后立即留痕（spec/plan 状态 `approved` + 「确认与复核」节，incident 时间线补「用户确认」条目），`done` 只在关单出现。**L2/L3 机器前置**：起草 spec 时 fill-spec / confirm-doc 校验「时间线含『用户确认』留痕」，未过即拒（exit 2）——被拒回本流程补留痕。
 
-### 4. 确认后落地
+### 1.5 确认后落地
 
 1. **开工前先配 plan**：复制 `workflow/plans/_TEMPLATE.md` 建 incident 同名 plan（L1 极简形态填「改动面 + 验证方式」两节即可）——incident≡intent 免掉的是 intent，**plan 不可免**（pre-commit 增量配对门禁与 pre-push check-loop 均按同名硬拦）
 2. 结构性修复:L1 走 `build.md` → `test.md`;L2/L3 先走 `design.md` 再进 `build.md` → `test.md`
-3. 三件套落地:防复发验证按 §2②、规范条目按 §2③ 落点优先级逐条落
+3. 三件套落地:防复发验证按 §1.3②、规范条目按 §1.3③ 落点优先级逐条落
 4. 若选「需要新 intent」→ 进 `next: .agents/commands/plan.md` 立新 intent 追踪
 
-## 技能辅助(可选,宿主级 skills)
+## 2. 技能辅助(可选,宿主级 skills)
 
 - 根因诊断:难复现/跨层问题用 `diagnosing-bugs` 走诊断循环(红→最小化→假设→插桩→修复→回归)
 - 事故定性/分级:参考 `triage` 技能的状态机思路;产出仍落 incident 模板,不引外部 tracker
 - 处置决策需用户离线拍板:用 `to-questionnaire` 生成问卷
 
-## 子代理调用约定
+## 3. 子代理调用约定
 
 - 事故诊断、止血选项、根因定性、incident 与三件套起草均由主智能体负责,不委派;用户选定止血方案后,仅有明确复现路径、授权文件与验收条件的局部热修可委派 `implementer`(数据 / Schema / 权限 / 安全 / 破坏性操作不得委派)。
 - 常规结构性修复按级别回流(L1 走 `build.md`;L2/L3 走 `design.md`),不在 Maintain 绕过前置门禁;子智能体返回后由主智能体检查 diff 并补跑 `test.md`。
 
-## 确认后
+## 4. 确认后
 
-- incident 状态 → fixed(三件套全落地)；防复发用例通过后 → closed——两跳均走确认门 `node .agents/scripts/confirm-doc.mjs <path>`（open→fixed / fixed→closed，无单跳；2026-09-28 起 check-loop 15 对账，AI 不得直改状态）
+- incident 状态 → fixed(三件套全落地)；防复发用例通过后 → closed——两跳均走确认门 `node .agents/scripts/confirm-doc.mjs <path>`（open→fixed / fixed→closed，无单跳；2026-09-28 起 check-loop 15 对账，AI 不得直改状态；口径见根 `AGENTS.md` §1.3 确认门）
 - 若需新 intent → 进 `next: .agents/commands/plan.md`

package/modules/hosts/trae/commands/wf-new-task.md

@@ -7,7 +7,7 @@ description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复
 
 > 6 阶段指令索引。AI 读 AGENTS.md 后按阶段路由,不并阶段、不跳阶段。
 
-## 6 阶段指令索引
+## 1. 6 阶段指令索引
 
 | 阶段 | 指令 | 触发短语 | 可委派子智能体 | 确认点 |
 |------|------|---------|----------------|--------|
@@ -19,7 +19,7 @@ description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复
 | **Maintain** | [.agents/commands/maintain.md](.agents/commands/maintain.md) | "线上出事了" / "记一笔 incident" | `implementer`(方案确认后) | 三件套要点确认 |
 | **Review**(横切,不占 6 阶段) | [.agents/commands/review.md](.agents/commands/review.md) | "评审一下" / "过 review 标准" | `independent-reviewer`(L2/L3 必须独立复核) | 问题定性与合入时机确认 |
 
-## 风险定级(第 0 步,先定级再路由)
+## 2. 风险定级(第 0 步,先定级再路由)
 
 动工前先按下表定风险级 L0-L3(就高不就低;判据细则见下节「级别判断」),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
 
@@ -30,24 +30,24 @@ description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复
 
 > 定级结果落 intent frontmatter `risk_level`(=级别,`fill-intent.mjs` 自动写入,机器选道用);协作道勾触达红线会被 check-loop 判「红线判低」hard 拦(就高升级 L2/L3 并补同名 spec)。
 
-## 路由判断
+## 3. 路由判断
 
 - **自动化驱动（并列入口,可选）**:一句话全程走 [pipeline-run.md](pipeline-run.md)——状态机驱动+工单协议+原话代录,与下述手动路由二选一,同一任务不混用
 - **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
 - **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
   - L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 Quick-Plan → `test.md`
- - L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
- - 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
+  - L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
+  - 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
 - **改完代码要验证**:直接进 `test.md`（验证通过即关单；L1 到此结束）
 - **合入前评审**:直接进 `review.md`(横切,P0/P1/P2 分级清单 + L2/L3 独立复核)
 - **准备上线**:直接进 `deploy.md`（仅 prod；文档应已在 test 关单）
 
-## 级别判断(AGENTS.md 第 3 条)
+## 4. 级别判断(AGENTS.md 第 3 条)
 
 | 级别 | 改什么 | 流程 |
 |------|--------|------|
 | L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
-| L1 | **实现级改动**(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) $\rightarrow$ 实现 $\rightarrow$ 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行；无确认来源只迁移不落账 |
+| L1 | **实现级改动**(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行；无确认来源只迁移不落账 |
 | L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
 | L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
 
@@ -67,12 +67,12 @@ description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复
 > **L1 是默认档**:红线全不勾即 L1,无需正列举——判级只回答「是否命中 L2 四类或 L3 结构面」。
 > **L3 的「DI 链」按组合根与运行时管线理解**:DI 注册、中间件/认证管线、服务构造器依赖变更(先例:本仓 workflow/ 留痕中无 schema 变更仍定 L3 的同类历史)。
 
-## intent 豁免(避免小改动也走完整闭环)
+## 5. intent 豁免(避免小改动也走完整闭环)
 
 - **L0 新需求**:可直接处理；**L1 新需求**:立轻量 intent + plan(不必 spec)
 - **docs 级改动**(AGENTS.md / workflow/ 模板 / .agents/ 脚本与 commands / yaml):豁免 intent,走 Conventional Commits 直接 commit;若同时触及代码,按代码部分级别立 intent
 - **bootstrap 类改动**(引入规则本身):豁免 intent,commit message 显式声明 `bootstrap`
 
-## 闭环兜底
+## 6. 闭环兜底
 
 - 门禁清单与判据以 `.githooks/` / `.agents/hooks/` / `check-loop.sh` 头部注释为准(本文件不复述、不写项数);hard-block = 配对断裂 / 回路断档 / 新建 done 未勾验。本地机器门只有本地钩子,禁 `--no-verify`(见根 `AGENTS.md`)。

package/modules/hosts/trae/commands/wf-pipeline-run.md

@@ -8,7 +8,7 @@ description: pipeline-run 自动化驱动入口——单命令驱动六阶段闭
 > 确定性部分由 `pipeline-run.mjs` 状态机驱动（机器门序列：fill-* → confirm-doc → verify.mjs → git，退出码全记录）；
 > AI 槽位经工单协议交宿主执行；人件门到点即停、原话代录。宿主只按本协议驱动，不自行改状态。
 
-## 驱动协议（宿主 AI 逐条执行）
+## 1. 驱动协议（宿主 AI 逐条执行）
 
 1. **启动**：`node .agents/scripts/pipeline-run.mjs start "<需求原文>"`（可预判则加 `--hint "kind=… level=… module=…"`）。
 2. **循环读停机点**：每次命令的 stdout 末行是机器标记 `PIPELINE-STOP <type> …`，按 type 分流：
@@ -24,13 +24,13 @@ description: pipeline-run 自动化驱动入口——单命令驱动六阶段闭
 3. **放弃**：用户明确不做时 `abort --run <id> --to superseded|cancelled --delegated "<原话>"`（approved 文档逐份走 confirm-doc --to）。
 4. **观测**（可选）：`status [--run <id>] [--json]` 全量事件流水；`watch` 终端轮询视图。
 
-## 硬纪律（违反即协议破坏）
+## 2. 硬纪律（违反即协议破坏）
 
 - 状态迁移唯一入口是脚本内部的 confirm-doc 调用——宿主**永不直改** workflow 文档 frontmatter 状态。
 - `--delegated` 的原话必须是用户当次对话原话（台账 `confirmations.jsonl` 留痕可对质）。
 - 修复环超限（3 次）时停机交人工，不带病推进；verify 非绿不关单。
 - run 文件（.agents/cache/pipeline-runs/）是脚本亲写的机器事实——宿主只读不写。
 
-## 与 new-task 的关系
+## 3. 与 new-task 的关系
 
 本命令是**自动化驱动的并列入口**（单命令走全程）；new-task.md 是手动阶段路由入口。同一套门禁与确认语义，二者只选其一驱动一个任务，不混用。

package/modules/hosts/trae/commands/wf-plan.md

@@ -7,35 +7,34 @@ description: Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不
 
 > AI 起草,用户确认。确认前不进下一阶段。
 
-## 执行
+## 1. 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；端口 8933 起自动上探，链接以脚本输出为准；不开看板不影响任务流程）。
 
-1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
+1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）。
 2. 否则起草新 intent:
-   - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收，新 intent 引用（防重复立项 / 重复踩坑）
+   - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收,新 intent 引用（防重复立项 / 重复踩坑）
    - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段（含 risk_level）+ 9 节（背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核）的草稿；AI 据此填实，模板与节标题机器保证不出错
    - 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
    - frontmatter 填 `模块:`（词表见 `.agents/workflow-modules.txt`，新建文档必填，check-loop 会警告）
    - 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准（L1 微改动可省非目标/约束两节，不硬填）
    - 红线勾选对照根 `AGENTS.md` 红线/约束相关节（如「项目适配区」「门禁与提交」）+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
-3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
-4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
+3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填。
+4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认。
+   **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件调用+逐件原话 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 
-   **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
-
-## 技能辅助(可选,宿主级 skills)
+## 2. 技能辅助(可选,宿主级 skills)
 
 - 需求模糊、判据写不出时:用 `grilling`/`grill-me` 拷问需求,答完回填 6 节
 - 需要用户离线拍板的决策:用 `to-questionnaire` 生成问卷,问题清单随 intent 草稿一并列出
 - 讨论中需同时沉淀术语表/ADR:用 `grill-with-docs`,文档落 `workflow/` 下与主题同名
 - 技能只辅助澄清,产出仍按 `_TEMPLATE.md` 落 `workflow/intents/`,确认门不变
 
-## 执行主体
+## 3. 执行主体
 
 - 需求澄清、级别判断与 intent 起草由主智能体负责,本阶段不委派子智能体。
 
-## 确认后
+## 4. 确认后
 
 - intent 状态 draft → approved
 - 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)——**提交最早可行点**：入口文档受 pre-commit 闭环配对（增量）门约束，同名 spec / plan 须已在工作区（先例 61ec130）

package/modules/hosts/trae/commands/wf-review.md

@@ -10,7 +10,7 @@ description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级
 > 参考 Anthropic REVIEW.md 做法。宗旨是**用户决策 + AI 协作**：AI 跑机器门禁、自查、出分级清单与建议；用户确认问题定性与合入。把"该机器兜底"与"靠 AI 自查"分开列明，避免注意力耗在机械逐行上。
 > 本文件为通用骨架;项目专属红线 / 命名 / 组件约定的具体口径在项目适配区（目录级 `AGENTS.md` 与 `.agents/hooks/`）补充。
 
-## P0 必拦（优先机器兜底，hook 覆盖不到的靠 AI 自查）
+## 1. P0 必拦（优先机器兜底，hook 覆盖不到的靠 AI 自查）
 
 - **架构红线**：分层依赖方向约束(如领域 / 应用层禁直接引用基础设施实现;豁免清单见目录级 `AGENTS.md` / 项目适配区)
   - 机器兜底：项目自有架构门禁(如有,`.agents/hooks/`)
@@ -22,7 +22,7 @@ description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级
   - 机器兜底：项目验证测试覆盖(如有) + AI 自查
 - **L2 / L3 改动无 spec**：拒收，先回 `workflow/specs/` 立 spec 确认通过
 
-## P1 应拦（自查重点）
+## 2. P1 应拦（自查重点）
 
 - **DB 命名与迁移**：遵循项目表 / 字段 / 外键命名规范与 schema 变更流程(见目录级 `AGENTS.md`);不得擅自引入项目未采用的迁移机制
 - **前端形态**：新增 / 编辑与大数据量选择等交互遵循项目组件约定(弹层 vs 跳页、选择器形态、表格与样式统一等)
@@ -35,14 +35,14 @@ description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级
 - **spec 承诺的断言落地**：spec §测试列出的用例 / 断言须真落到测试或验证脚本；「写进 spec」不等于「跑得起来」，且常驻断言禁写成随时间增长的行数常量
 - **跨宿主薄适配正文漂移**：改 `templates/_agents/{commands,roles}/*.md` 后必须跑 `flow-kit sync-hosts --apply` 单向同步注册表内全部宿主薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）；装户视角由 `flow-kit doctor` §6.7 检查（包源环境 §6.7 skipped）
 
-## P2 建议（提醒，不拦合入）
+## 3. P2 建议（提醒，不拦合入）
 
 - 样式统一性（深色 / 浅色主题、卡片样式）
 - 注释完整性（复杂逻辑处补注释，AGENTS.md 已说的不重复）
 - Conventional Commits 中文（feat / fix / docs / style / refactor / perf）
 - 历史同类 incident 的复盘三件套是否补齐
 
-## 审查分工（用户决策 + AI 协作）
+## 4. 审查分工（用户决策 + AI 协作）
 
 - **机器兜底**（pre-commit / pre-push / test 自动拦，无需人守）：门禁清单与判据以 `.githooks/`、`.agents/hooks/`、`check-loop.sh` 头部注释为准；`项目测试命令` 跑自动化用例。
 - **AI 复核**：机器门禁完成后优先委派 `independent-reviewer`，聚焦 P0 hook 未覆盖项 + 全部 P1（P2 视精力）——产出分级问题清单 + 修复建议。复核方法参考 `code-review` 技能（Standards×Spec 双轴）；每条 finding 报告前过 `review-verification-protocol` 防误报门（锚定 file:line、给出证据、校准严重级，不确定就降级为提问）。

package/modules/hosts/trae/commands/wf-source-sync-check.md

@@ -10,16 +10,16 @@ description: 装户面同步一致性检查（包源 templates/_agents/ vs 装
 > `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告：缺失 / 孤儿 / 漂移。
 > managed 文件由 `flow-kit sync` 跟踪；owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带（结构级差异）。
 
-## 何时跑
+## 1. 何时跑
 
 - 改 `templates/_agents/*` 包源后
 - 怀疑装副本未跟包源更新
 - 体检装副本完整性（清理前 / 发版前）
 - 不跑：仅改装副本 `.agents/*`（B-b 决策「只报告」+ 不反向同步）
 
-## 怎么跑
+## 2. 怎么跑
 
-### 默认 `--diff`（仅报告）
+### 2.1 默认 `--diff`（仅报告）
 
 ```
 node .agents/scripts/source-sync-check.mjs --diff
@@ -36,7 +36,7 @@ node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path>   #
 - `templates/_agents/cache/`（运行时缓存，与 `flow-kit sync` 既有约定一致）
 - `.agents/kit.json` / `.agents/settings.json`（init 渲染产物，不属双源）
 
-### 输出示例
+### 2.2 输出示例
 
 ```
 ▶ flow-kit source-sync-check --diff
@@ -51,7 +51,7 @@ node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path>   #
     - scripts/ensure-board.mjs  pkg=e66653b0…  tgt=b6f3cc9b…
 ```
 
-### 自验
+### 2.3 自验
 
 ```
 node .agents/scripts/source-sync-check.test.mjs   # 11 场景全过
@@ -59,7 +59,7 @@ npm test                                            # 含 source-sync-check 套
 flow-kit doctor                                     # 10/0/0
 ```
 
-## 边界（不要做）
+## 3. 边界（不要做）
 
 - 不要自动化同步（B-b 决策「只报告不修复」——与 `gate-checklist` 同源）
 - 不改 managed 台账跟踪逻辑（`sync.mjs` 不动）
@@ -67,7 +67,7 @@ flow-kit doctor                                     # 10/0/0
 - 不反向同步——装副本独自有文件（如 hooks/commit-check.config.json）可能是装户配置，不应被删
 - 不检查注册表内宿主 `modules/hosts/` 薄适配漂移（那是 `flow-kit sync-hosts` 范围）
 
-## 当前已识别的真实漂点（首次实测，2026-09-25）
+## 4. 当前已识别的真实漂点（首次实测，2026-09-25）
 
 - **缺失**：本工具写完后未同步装副本（预期内——随本次 commit 解决）
 - **孤儿**：`.agents/hooks/commit-check.config.json`（装副本独有，疑似装户配置）
@@ -75,7 +75,7 @@ flow-kit doctor                                     # 10/0/0
 
 修复留后续 incident / intent 跟踪（不在本次范围）。
 
-## 与既有工具的关系
+## 5. 与既有工具的关系
 
 | 工具 | 作用域 | 算法 |
 |---|---|---|
@@ -85,8 +85,8 @@ flow-kit doctor                                     # 10/0/0
 
 三者互补，不重叠。
 
-## 相关留痕
+## 6. 相关留痕
 
 - intent：`workflow/intents/2026-09-25-source-sync-check.md`
 - plan：`workflow/plans/2026-09-25-source-sync-check.md`
-- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（包源改了装副本未同步——本工具预防性体检）
+- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（包源改了装副本未同步——本工具预防性体检）

package/modules/hosts/trae/commands/wf-sync-hosts.md

@@ -13,16 +13,16 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 > 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
 > 目标根取 `--dir <目录>` > 当前目录。
 
-## 何时跑
+## 1. 何时跑
 
 - 改 `templates/_agents/commands/*.md` 正文后（11 个 commands 文件）
 - 改 `templates/_agents/roles/*.md` 正文后（3 个 roles 文件）
 - 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
 - 不跑：仅改 frontmatter；改 trae 钩子/规则；改包源其他文件
 
-## 怎么跑
+## 2. 怎么跑
 
-### 默认 `--diff`（仅报告）
+### 2.1 默认 `--diff`（仅报告）
 
 ```
 node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
@@ -36,7 +36,7 @@ flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或
 - **⚠️ 权威源声明但薄适配缺失** — `add-host <h>` 接管后跑 `--apply` 才会装（apply 不自动创建）
 - **⚠️ 孤儿薄适配（权威源无对应文件）** — 历史残留或宿主特化，apply 不删
 
-### `--apply` 单向同步
+### 2.2 `--apply` 单向同步
 
 ```
 node bin/flow-kit.mjs sync-hosts --apply
@@ -44,7 +44,7 @@ node bin/flow-kit.mjs sync-hosts --apply
 
 按权威源正文覆盖薄适配正文段；薄适配原 frontmatter 保留（trae name: wf-X、opencode 描述、zcode/omp 中文风格各自不动）。apply 不反向同步——薄适配手改了正文也会被覆盖（这是设计选择，避免漂移方向歧义）。
 
-### 自验
+### 2.3 自验
 
 ```
 npm test                                       # 含 sync-hosts.test.mjs 8 场景
@@ -52,7 +52,7 @@ node bin/flow-kit.mjs doctor                   # 装户跑 §7.x PASS；包源
 sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已探测分流
 ```
 
-## 边界（不要做）
+## 3. 边界（不要做）
 
 - 不要 `--apply` 反向同步（写权威源）：权威源是真相，薄适配手改会被覆盖——这是设计，apply 前先看 `--diff`
 - 不要删除孤儿薄适配：可能是宿主特化或历史残留，apply 不动
@@ -60,14 +60,14 @@ sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已
 - 不要把「避免与权威版本漂移」明文加回去——这是旧契约的指针风格，已被 B-b 正文副本取代
 - 装了新宿主后跑 `--apply`：新宿主目录空白，apply 不会自动创建薄适配（薄适配须经 `add-host <h>` 接管）
 
-## 不在本次同步范围
+## 4. 不在本次同步范围
 
 - trae 钩子（`modules/hosts/trae/hooks/*.cjs`）— 独立演进的工程件
 - trae 规则（`modules/hosts/trae/rules/*.md`）— 同上
 - 包源 .agents/scripts/*.cjs（pre-commit 等钩子）— 同步由 `flow-kit sync` 走 managed 台账负责
 
-## 相关留痕
+## 5. 相关留痕
 
 - intent：`workflow/intents/2026-09-25-cross-host-sync.md`
 - plan：`workflow/plans/2026-09-25-cross-host-sync.md`（含 B-b 方案拍板）
-- incident：`workflow/incidents/2026-09-25-wf-runtime.md`（双源纪律教训，规范 §7.x 包源环境跳过）
+- incident：`workflow/incidents/2026-09-25-wf-runtime.md`（双源纪律教训，规范 §7.x 包源环境跳过）

package/modules/hosts/trae/commands/wf-test.md

@@ -47,20 +47,19 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 复核者读入口文档(intent / incident) + spec + plan + diff,判断变更意图与风险
 - 复核意见交用户定性(采纳 / 驳回);采纳项回 `build.md` 修改
 
-## 子代理调用约定
+## 5. 子代理调用约定
 
 - 静态门不委派;UI 实测委派 `ui-verifier`(静态门通过后)、独立复核委派 `independent-reviewer`,均要求读取对应 `.agents/roles/*.md`;宿主不支持时按 frontmatter `fallback`(reviewer 必须另开新会话,不得主智能体自查冒充)。
 - 子智能体只返回证据与结论——失败项修复仍回 `build.md`,不得在 Test 阶段顺手改代码;修复后重跑本阶段,全过后用户确认再关单。
 
-## 确认后
+## 6. 确认后（关单）
 
-- 输出测试报告(通过项 / 失败项)
-- 失败项已修复并复测通过
+- 输出测试报告(通过项 / 失败项);失败项已修复并复测通过。
 - **关单**（日常闭环点，不依赖是否上 prod）:
   - 关单前一键过门：`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**`--doc` 把测试绿凭证绑到本单**——不带它落下的绿行不给任何单背书，confirm-doc 前置与检查 8 对账只认带本单 `--doc` 的绿行（仅 v6+ 生效）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
-  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
+  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent → done；同名 spec/Quick-Plan（若有）仍 approved → done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
-**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
+  - **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（两形态 / 逐件+逐件原话 / done 内容绑定（关单编辑先于 done 确认、confirm-doc 是最后一次写入）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
   - 修复：防复发验证已落地，incident → closed（经确认门 confirm-doc：open→fixed / fixed→closed 两跳、无单跳；2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认，口径同 done 内容绑定）
   - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
   - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）

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

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

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

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

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

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

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "agentic-flow-kit",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {
     "test": "node src/run-tests.mjs",
+    "lint": "eslint .",
     "prepack": "node -e \"require('fs').rmSync('templates/_agents/cache',{recursive:true,force:true})\" && node scripts/check-pack-eol.mjs"
   },
   "bin": {
@@ -41,5 +42,9 @@
   "bugs": {
     "url": "https://github.com/zerosloney/agentic-flow-kit/issues"
   },
-  "homepage": "https://github.com/zerosloney/agentic-flow-kit#readme"
+  "homepage": "https://github.com/zerosloney/agentic-flow-kit#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "eslint": "^9.39.4"
+  }
 }

package/src/doctor.mjs

@@ -10,7 +10,7 @@ import { isOwned, HOSTS, pickStackVars, srcTemplatePath, templateDriftOf, TEMPLA
 // 宿主目录映射（与 src/profiles.mjs#HOSTS 同源：装副本目录名前缀带点）
 const HOST_DIR = Object.fromEntries(Object.entries(HOSTS).map(([k, v]) => [k, v.dir]));
 // 命令层薄适配宿主：[装副本目录名, 文件名前缀]（单源 profiles.mjs#HOSTS.commandPrefix；与 sync-hosts pairsFor 同口径）
-const HOST_CMD_DIR = Object.entries(HOSTS).filter(([, v]) => v.commandPrefix).map(([k, v]) => [v.dir, v.commandPrefix]);
+const HOST_CMD_DIR = Object.entries(HOSTS).filter(([, v]) => v.commandPrefix).map(([, v]) => [v.dir, v.commandPrefix]);
 
 function sh(cmd, cwd) {
   try {

package/src/init.test.mjs

@@ -83,7 +83,7 @@ check('合并：原内容为空时骨架即全文', mergeAgents('', '<!-- m -->\
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'init-p1-'));
   const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
   const vars = { BOARD_PORT: '8933' };
-  const t = renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
+  renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
   // P1-1：renderTree 落盘执行位——win32 下 statSync().mode 无 0o111 语义（恒 0666 系），
   // 断言「writeFileSync 带 mode 参数不炸 + POSIX 语义表达」；真值在 POSIX CI 腿验证
   const hookStat = fs.statSync(path.join(tmp, '.githooks', 'pre-commit'));

package/src/run-tests.mjs

@@ -1,6 +1,9 @@
-// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs 套件。
+// run-tests.mjs — 全套测试入口（npm test）：lint 首步 + CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs 套件。
 // 顺序执行、任一非零整体失败（exit 1）。check-loop 套件自 2026-09-26 check-loop-node 起为 node 实现
 // （check-loop.test.mjs 由下方 glob 自动发现——旧 bash 特判与「无 sh 跳过」提示随迁移退役）。
+// lint 首步（2026-10-08 engine-quality-batch）：eslint 仅 devDependency（包源仓）——检测到未安装时
+// 显式打印 skip 后继续（裸 checkout 未 npm install 场景的可诊断性；装户仓无本编排器不涉及），
+// 已安装但报错则 fail-closed 计入失败。
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -25,6 +28,17 @@ const nodeSuites = [
 ];
 
 let failed = 0;
+
+// lint 首步：eslint 可用性探测 = require.resolve 于包源仓 node_modules（裸 checkout 解析失败 → 显式跳过）
+console.log('\n===== lint（eslint .）=====');
+const eslintEntry = spawnSync(process.execPath, ['-e', "require.resolve('eslint')"], { cwd: ROOT, encoding: 'utf8' });
+if (eslintEntry.status !== 0) {
+  console.log('[lint] skipped: eslint not installed（npm install 后启用；仅包源仓场景）');
+} else {
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'node_modules/eslint/bin/eslint.js'), '.'], { cwd: ROOT, stdio: 'inherit' });
+  if (r.status !== 0) failed++;
+}
+
 for (const rel of nodeSuites) {
   console.log(`\n===== ${rel} =====`);
   const r = spawnSync(process.execPath, [path.join(ROOT, rel)], { cwd: ROOT, stdio: 'inherit' });