agentic-flow-kit 1.8.2 → 2.0.0

package/templates/scaffold/workflow/specs/_TEMPLATE.md

@@ -0,0 +1,87 @@
+---
+状态: draft
+级别: L1
+模块: <词表之一，见 .agents/config/workflow-modules.txt>
+---
+# SPEC — <与入口文档同名主题>
+<!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2 / L3 必须先有 spec 确认通过方可起草 plan；L1 可省略 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled（done=关单、superseded=曾确认后放弃、cancelled=未完成即取消）；L3 确认通过后在 frontmatter 追加两行：`确认结果: approved` 与 `确认时间: YYYY-MM-DD`（check-loop 对 L3 强制校验） -->
+<!-- 模糊点纪律（2026-10-16）：起草/修订遇无法自行决策的模糊点（多种解释/口径缺失/依赖外部事实）禁止脑补——在对应节原地插入 [NEEDS CLARIFICATION]: <一句话问题> 并保持 draft 向用户求澄清；澄清后删除标记、把决策落为正文。approved 前标记须清零（口径见 workflow/README.md 文档协议「模糊点显式阻断」）。 -->
+
+对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）
+
+## 功能行为
+<讲清功能怎么工作；分小节列用户 / 系统行为，必要时附状态机 / 时序图说明>
+
+## 数据流
+<数据从哪里来 → 经过哪些处理 → 落到哪里；含字段映射、接口契约、上下游依赖>
+
+## 系统改动清单
+- 后端：模块 / 文件 / 接口契约
+- 数据库：无 / <表名 + 字段 + 迁移 SQL 路径>
+- 前端：路由 / 组件 / store / api
+
+## 约束遵守映射（对照 AGENTS.md 触达红线）
+<!-- 2026-10-29 起：映射须覆盖项目目录 AGENTS.md 的机器门/红线条目（与本次改动面无关——全仓契约基准，起草前必读，见 stages.md Design §2「必读输入」）；wiki 依据在相关节以路径引用 -->
+| 红线 | 本 spec 如何满足 |
+|------|------------------|
+| Application 禁引 Infrastructure / DbContext | <通过 XXX，不引入 YYY> |
+| 规则 / 契约（编码权威 / 共享契约 / 既有接口语义 / 全局横切口径） | <是否触及（触及即 L2 定级依据）；编码权威仍在后端> |
+| schema / 迁移 SQL（禁 dotnet ef） | <涉及 SQL 路径；历史 EF Migrations 目录（含 ModelSnapshot）已整体移除，不得重建> |
+| 前端：Drawer / 禁 a-select / style.css 统一 | <本 spec 涉及哪些前端约定> |
+
+## 验收判据
+<!-- 判据级收敛对账的机器输入（check-loop 检查 23）：每行一条判据，「证据」须机器可解析。
+     路径：文件必须存在。机器不读正文，不判断它和判据是否相关（那一步留给新会话复核）。
+     命令：只认全量门跑过的 npm test / dotnet test / dotnet build / npm run build / verify.mjs。
+     自 convergenceHardSince 起，还须 workflow/verify-evidence.md 有一行时间不早于本 spec「日期」的全绿凭证；没有这行 = 未覆盖。
+     日期口径：frontmatter「日期」与全绿行时间同为 UTC（fill-spec 默认即此）；手写勿用本地时区日期——UTC+8 凌晨 0–8 点落的全绿行日期为前一日，会对不上（硬拦，08:00 后重跑门即解）。
+     verify-ui / vue-tsc / regression-smoke 等不在全量门里，改记证据文件路径。
+     「状态」写「覆盖」而证据无效仍判未覆盖。人工走查状态写「人工」，证据列留空（仅「人工+空证据」豁免机器对账；截图等图片不在路径白名单，需留痕改存 .md 报告后引路径）。
+     无本节或表为空 → WARN。证据无效：仅 convergenceSince 时 WARN；convergenceHardSince 起 HARD-BLOCK。 -->
+| 判据（可观察行为） | 证据（测试文件 / 命令 / 证据文件） | 状态 | 对应验收 |
+|---|---|---|---|
+| <行为 1> | <路径或命令> | <覆盖 / 未覆盖 / 人工> | <A1 或 A1、A3> |
+
+<!-- 「对应验收」列 = 入口 intent 验收编号（锚 coverageSince 2026-10-22 起确认门强制）：每条 An 至少被引用一次，
+     可一对多；技术性判据无可对应验收时留空即可（只做单向覆盖，不反向逼假验收）。判据门见 stage-gates coverageGate。 -->
+
+## 风险评估
+- <风险点 1> ｜ 应对：<测试 / hook / 评审>
+- <风险点 2> ｜ 应对：…
+
+## 前提质询
+<!-- 拦「自信的错误解读」（premise-interrogation 2026-10-29；根因 incidents/2026-10-23-pml-quota-substitute-identity-overwrite：
+     展示诉求被写成存储身份改写，测试按错前提固化期望、复核只核自洽——三层同源失效，唯一可拦点在前提进事实源之前）。
+     每行一个立论前提：反问对立解读、结论写凭什么选定；无解读风险的小件写一行「无关键前提」+ 理由。
+     confirm-doc 硬拦（premiseSince 2026-10-30 锚起）：缺节 / 空表 / 占位未填 / 缺反问或缺依据 → 拒。 -->
+| 前提 | 反问（对立解读会怎样） | 结论与依据 |
+|---|---|---|
+| <立论的解读 / 口径选择> | <换成对立解读会怎样、最坏后果> | <选定解读 + 凭什么（用户原话 / 文档 / 实验）> |
+
+## 歧义清单
+<!-- 6 维各一行、待澄清归零方可确认；工序与判据单源见 .agents/commands/stages.md Design §2.7 与 stage-gates clarifyGate。
+     缺维 ≠ 无歧义；锚前存量、缺 frontmatter「日期」者不参与。 -->
+| 维度 | 结论 | 依据 / 问题 | 状态 |
+|---|---|---|---|
+| 状态与边界 | <谁在什么状态能做什么；越权 / 并发 / 幂等？> | <状态机节号或代码路径> | <已定 / 待澄清> |
+| 数据口径 | <空值、精度、单位、时区、排序稳定性？> | <查库结果或既有实现> | <已定 / 待澄清> |
+| 失败路径 | <部分成功是否回滚、重试、用户看到什么提示？> | <依据> | <已定 / 待澄清> |
+| 契约对称 | <≥2 个消费方是否同口径；旧调用方如何兼容？> | <消费方清单> | <已定 / 待澄清> |
+| 存量数据 | <历史行如何解释；是否需回填？> | <数据分布实测> | <已定 / 待澄清> |
+| 验收可测性 | <每条验收能否被一条命令或一次实验判定？> | <测试文件或命令> | <已定 / 待澄清> |
+
+## 假设与推断
+<!-- 只登记推断（无实验 / 代码 / 文档支撑的口径选择），不登记实测事实；无推断则删本节。 -->
+| 假设 | 影响面 | 若不成立会怎样 |
+|---|---|---|
+| <一句话假设> | <受影响模块 / 端点 / 页面> | <返工范围与兜底> |
+
+## 确认与复核
+> AI-Native 工作流：确认 = 用户在对话内一句话通过；无第二审批人，追溯靠 git（commit 记录确认时点）。
+> 确认结果 / 确认时间写在文件头 frontmatter（L3 由 check-loop 强制校验）；本节只留叙述性复核记录。
+
+- 独立复核：<L3 强制：另开新会话由 AI 复核本 spec，记录复核会话与结论；L1 / L2 无则删除本行。2026-10-12（reviewerSince）起复核行须含「复核上下文：<会话/子代理 id>」>
+- 复核结论：<无则删除本行>
+- 返修意见：<无则删除本行>
+- 确认通过后，方可起草 ../plans/YYYY-MM-DD-<主题>.md

package/templates/scaffold/workflow/verify-evidence.md

@@ -0,0 +1,4 @@
+# 测试绿凭证对账（生成物，勿手改）
+
+> 由 `node .agents/scripts/gen-verify-evidence.mjs` 从 `.agents/verifications.jsonl` 重生成。
+> 新装户占位；首次生成后自动填充。

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 agentic-flow-kit contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/modules/gates/README.md

@@ -1,25 +0,0 @@
-# 门禁模块
-
-可选红线。`flow-kit add-gate <名>` 把模块里除元数据外的文件平铺进 `.agents/hooks/`，并把 `local-pre-commit.line` 的那一行追加到 `.agents/hooks/local-pre-commit`。装完归项目所有，`sync` 不覆盖。
-
-## 约定
-
-| 文件 | 作用 |
-|---|---|
-| `check-*.mjs` 或其他脚本 | 拷入 `.agents/hooks/`，由 pre-commit 调用 |
-| `local-pre-commit.line` | 一行挂载命令，不拷入项目；已有相同行则不重复 |
-| `README.md` | 只留在包内 |
-
-脚本只看暂存区，退出码非 0 即拦住这次提交。不要在模块里放子目录。
-
-## 现有模块
-
-| 名 | 拦住什么 |
-|---|---|
-| `dotnet-ca` | Clean Architecture 分层红线（参考实现） |
-| `node-layer` | `src/` 引用 `tests/`、`test/`、`__tests__/` |
-| `py-import` | 业务 `.py` 引用 `tests` / `test` 包 |
-| `generated-readonly` | 手改 `GENERATED:BEGIN` 与 `GENERATED:END` 之间的行 |
-| `test-protect` | fix/调试提交里测试文件与被测代码同框改动（豁免：`FLOW_KIT_ALLOW_TEST_EDIT=1`） |
-
-项目自己的红线复制其中一个目录，改判断，再用 `add-gate` 装上。

package/modules/gates/dotnet-ca/README.md

@@ -1,24 +0,0 @@
-# dotnet-ca — Clean Architecture 门禁模块（可选）
-
-Clean Architecture（Application/Domain/Infrastructure/API 分层）红线守卫参考实现，抽自真实项目实战门禁。五条红线：Application 禁引 Infrastructure/DbContext、API Controller 禁直注 DbContext、EF 模型层解耦（无关系映射/无导航属性/无 Include）、InnerException 禁透传响应。
-
-## 接线（一次性，装进项目本地）
-
-已装 agentic-flow-kit 的项目直接：
-
-```sh
-npx agentic-flow-kit add-gate dotnet-ca
-```
-
-（装 .agents/hooks/check-architecture.sh + 自动接线 local-pre-commit；装后归项目所有，sync 不覆盖。）
-
-手动装法等价于：
-
-```sh
-mkdir -p .agents/hooks
-cp <包内 modules/gates/dotnet-ca/check-architecture.sh> .agents/hooks/
-# .agents/hooks/local-pre-commit（pre-commit 的项目门禁挂载点，没有则新建）：
-echo 'sh .agents/hooks/check-architecture.sh' >> .agents/hooks/local-pre-commit
-```
-
-然后改脚本头部 `CONFIG` 块的目录/类型名。红线不适用（如不用 EF）的条目自行删除——本模块是参考实现，装进项目后归项目所有。

package/modules/gates/dotnet-ca/check-architecture.sh

@@ -1,150 +0,0 @@
-#!/bin/sh
-# check-architecture（agentic-flow-kit · dotnet-ca 门禁模块）：Clean Architecture 红线参考实现
-# 红线：Application 禁引用 Infrastructure / 禁 DbContext / EF 模型层解耦（无关系映射/无导航/无 Include）/ 异常详情不透传
-# 违例输出到 stderr 并 exit 1；干净无输出 exit 0
-#
-# 接线（项目一次性）：把本文件复制/引用到 .agents/hooks/ 下并在 .agents/hooks/local-pre-commit 里执行——
-#   mkdir -p .agents/hooks && cp <包内路径>/check-architecture.sh .agents/hooks/
-#   echo 'sh .agents/hooks/check-architecture.sh' >> .agents/hooks/local-pre-commit
-cd "$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "check-architecture: 不在 git 仓库内,门禁 fail-closed,不静默放行" >&2; exit 1; }
-
-# ---- CONFIG：按项目改成你的目录/类型名（其余为通用逻辑，升级只动 CONFIG） ----
-APP_DIR="backend/src/YourApp.Application"
-API_DIR="backend/src/YourApp.API"
-DBCTX_FILE="backend/src/YourApp.Infrastructure/Data/AppDbContext.cs"
-DOMAIN_ENTITIES_DIR="backend/src/YourApp.Domain/Entities"
-CONTROLLERS_DIR="backend/src/YourApp.API/Controllers"
-DBCTX_CLASS="AppDbContext"
-INFRA_USING="using YourCompany.YourApp.Infrastructure"
-EXEMPT_CTRL="ExemptedController"      # 冒号分隔的豁免 Controller 名（原生 LINQ 等历史豁免）
-SHARED_TYPES="Staff,Company"          # 跨模块共享实体名（红线 4.3 白名单）
-# -------------------------------------------------------------------------
-
-# 门禁目标存在性：目标缺失时 fail-closed（不静默放行）
-require_target() {
-  [ -d "$1" ] || [ -f "$1" ] || { echo "check-architecture: 门禁目标缺失（$1）——fail-closed,不静默放行" >&2; exit 1; }
-}
-require_target "$APP_DIR"
-require_target "$API_DIR"
-violations=""
-# 豁免清单拆多 grep -e（2026-09-27 host-gates-p1 P1-B1）：POSIX BRE 中 | 是字面量——旧 tr ':' '|' 造的
-# "A|B" 模式永不命中，多值豁免全部失效（豁免 Controller 被误报违例）。
-# set -- + "$@" 派发（复核 P2-2 收口）：对任意值安全（含空格/glob 字符不拆宽豁免面）
-set --
-OLD_IFS="$IFS"
-IFS=':'
-for ex in $EXEMPT_CTRL; do
-  [ -n "$ex" ] && set -- "$@" -e "$ex"
-done
-IFS="$OLD_IFS"
-
-# 红线 1：Application csproj 不得引用 Infrastructure 项目
-# csproj 存在性 fail-closed（2026-09-27 host-gates-p1 随 P1-B3）：glob 展开失败时旧代码静默放行
-csproj_found=0
-for cs in "$APP_DIR"/*.csproj; do
-  [ -f "$cs" ] && csproj_found=1
-  if grep -q "Infrastructure" "$cs" 2>/dev/null; then
-    violations="$violations
-- csproj 引用了 Infrastructure 项目（Application 只允许依赖 Domain 与共享层）"
-  fi
-done
-[ "$csproj_found" -eq 1 ] || { echo "check-architecture: 门禁目标缺失（$APP_DIR/*.csproj）——fail-closed,不静默放行" >&2; exit 1; }
-
-# 红线 2：Application 代码不得出现 DbContext / Infrastructure 命名空间
-hits=$(grep -rn -e "$DBCTX_CLASS" -e "$INFRA_USING" "$APP_DIR" --include="*.cs" 2>/dev/null | grep -v -e "/obj/" -e "/bin/")
-if [ -n "$hits" ]; then
-  violations="$violations
-- Application 代码出现 DbContext / Infrastructure 引用：
-$hits"
-fi
-
-# 红线 3：API 层 Controller 禁直接注入 DbContext（豁免清单内的 Controller 除外）
-api_hits=$(grep -rn "$DBCTX_CLASS" "$API_DIR" --include="*.cs" 2>/dev/null | grep -v -e "/obj/" -e "/bin/" "$@")
-if [ -n "$api_hits" ]; then
-  violations="$violations
-- API 层出现 DbContext 直接引用（应走仓储/服务接口，豁免仅 $EXEMPT_CTRL）：
-$api_hits"
-fi
-
-# 红线 4.1：DbContext 禁关系映射配置（模型层解耦，关联一律显式 JOIN/分步查询）
-require_target "$DBCTX_FILE"
-rel_hits=$(grep -nE "HasOne|HasMany|WithOne|WithMany|HasForeignKey|OnDelete" "$DBCTX_FILE" 2>/dev/null)
-if [ -n "$rel_hits" ]; then
-  violations="$violations
-- $DBCTX_CLASS 出现关系映射（模型层已解耦）：
-$rel_hits"
-fi
-
-# 红线 4.2：Application / API 禁代码级 .Include(（注释里的「原 Include(...)」无前导点，不误报）
-inc_hits=$(grep -rnE "\.Include\(" "$APP_DIR" "$API_DIR" --include="*.cs" 2>/dev/null | grep -v -e "/obj/" -e "/bin/")
-if [ -n "$inc_hits" ]; then
-  violations="$violations
-- Application/API 出现 EF Include（导航已移除，明细/参照数据经仓储分步查询或显式 JOIN）：
-$inc_hits"
-fi
-
-# 红线 4.3：Domain 实体禁导航属性（按实体类名交叉扫描；枚举/标量属性不误伤）
-require_target "$DOMAIN_ENTITIES_DIR"
-PY_BIN=""
-for c in python python3 py; do
-    if command -v "$c" >/dev/null 2>&1; then PY_BIN="$c"; break; fi
-done
-if [ -z "$PY_BIN" ]; then
-  violations="$violations
-- 红线 4.3 无法执行：未找到 python/python3/py（Domain 导航属性扫描依赖 Python；门禁 fail-closed，不静默放行）"
-else
-    # 2026-09-24：①python 运行期报错也 fail-closed（原只对「没装 python」兜底，脚本报错时 nav_hits 为空即放行）；
-    # ②属性匹配改全文 finditer——支持「{ 换行」与 expression-bodied（=>）形态，先剥注释防误报
-    nav_hits=$(DOMAIN_ENTITIES_DIR="$DOMAIN_ENTITIES_DIR" SHARED_TYPES="$SHARED_TYPES" "$PY_BIN" - <<'PYEOF'
-import re, glob, os
-from os import environ
-d = environ['DOMAIN_ENTITIES_DIR']
-shared = {s.strip() for s in environ.get('SHARED_TYPES', '').split(',') if s.strip()}
-files = glob.glob(d + '/**/*.cs', recursive=True)
-names = set()
-for f in files:
-    with open(f, encoding='utf-8-sig') as fh:
-        names |= set(re.findall(r'public\s+(?:sealed\s+|abstract\s+|partial\s+)*(?:class|record)\s+(\w+)', fh.read()))
-hits = []
-for f in files:
-    with open(f, encoding='utf-8-sig') as fh:
-        src = re.sub(r'/\*.*?\*/', '', fh.read(), flags=re.S)
-    src = re.sub(r'//[^\n]*', '', src)
-    for m in re.finditer(r'\bpublic\s+(?:virtual\s+)?([\w<>, \t.\?]+?)\s+(\w+)\s*(?:\{|=>)', src):
-        typ = m.group(1).strip()
-        mm = re.search(r'(?:ICollection|List|IEnumerable|IReadOnlyCollection|IReadOnlyList)<\s*(\w+)\s*>', typ)
-        core = mm.group(1) if mm else (typ.rstrip('?') if re.fullmatch(r'\w+\??', typ) else None)
-        if core and (core in names or core in shared):
-            ln = src.count('\n', 0, m.start()) + 1
-            hits.append(f"{os.path.basename(f)}:{ln} {m.group(2)} : {typ}")
-if hits:
-    print('\n'.join(hits))
-PYEOF
-    ) || violations="$violations
-- 红线 4.3 无法执行：python 扫描异常退出（fail-closed，不静默放行；诊断见上方 stderr）"
-fi
-if [ -n "$nav_hits" ]; then
-  violations="$violations
-- Domain 实体出现导航属性（模型层已解耦，关联只保留外键标量列）：
-$nav_hits"
-fi
-
-# 红线 5：Controller 禁把 InnerException 原文透传进响应体（详情只许进日志）
-# CONTROLLERS_DIR fail-closed（2026-09-27 host-gates-p1 P1-B3）：旧代码 2>/dev/null 吞目录缺失——
-# Controllers 改名/改 minimal API 时本红线静默失效，违反脚本自述「目标缺失 fail-closed」硬约束
-require_target "$CONTROLLERS_DIR"
-# 已知天花板：grep 按整行排除 Log 调用——透传与 Log 写在同一行可绕过；语义级排除需 AST 工具，参考实现门禁按接受记录（2026-09-24）
-inner_hits=$(grep -rn "InnerException" "$CONTROLLERS_DIR" --include="*.cs" 2>/dev/null \
-  | grep -v -e "/obj/" -e "/bin/" \
-  | grep -vE "Log(Warning|Error|Information|Debug|Trace)")
-if [ -n "$inner_hits" ]; then
-  violations="$violations
-- Controller 出现 InnerException 透传进响应（数据库异常统一翻译；详情只许进日志）：
-$inner_hits"
-fi
-
-if [ -n "$violations" ]; then
-  printf '架构红线违例（dotnet-ca 门禁）：\n%s\n' "$violations" >&2
-  exit 1
-fi
-exit 0

package/modules/gates/dotnet-ca/local-pre-commit.line

@@ -1 +0,0 @@
-sh .agents/hooks/check-architecture.sh

package/modules/gates/generated-readonly/README.md

@@ -1,13 +0,0 @@
-# generated-readonly
-
-暂存 diff 若改到 `GENERATED:BEGIN` 与 `GENERATED:END` 之间的行，提交失败。生成器自己重写时：
-
-```sh
-FLOW_KIT_ALLOW_GENERATED=1 git commit
-```
-
-```sh
-npx agentic-flow-kit add-gate generated-readonly
-```
-
-标记写在文件正文里。`workflow/INDEX.md` 与 `wiki/INDEX.md` 的生成区已经带这对标记。

package/modules/gates/generated-readonly/check-generated.mjs

@@ -1,61 +0,0 @@
-#!/usr/bin/env node
-// 暂存 diff 不得改写 GENERATED:BEGIN / GENERATED:END 之间的行。
-// 区间按索引里的文件计算（git show :path），不读工作区。
-// 生成器重写该区域时设 FLOW_KIT_ALLOW_GENERATED=1。
-import { spawnSync } from 'node:child_process';
-
-if (process.env.FLOW_KIT_ALLOW_GENERATED === '1') process.exit(0);
-
-const git = process.platform === 'win32' ? 'git.exe' : 'git';
-const listed = spawnSync(git, ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' });
-if (listed.status !== 0) {
-  console.error('check-generated: git diff --cached 失败（需在 git 仓库的暂存区上运行）');
-  process.exit(1);
-}
-const diff = spawnSync(git, ['diff', '--cached', '-U0', '--'], { encoding: 'utf8' });
-if (diff.status !== 0) process.exit(1);
-
-function rangesOf(text) {
-  const out = [];
-  let start = -1;
-  String(text).split(/\n/).forEach((line, i) => {
-    if (line.includes('GENERATED:BEGIN')) start = i + 1;
-    else if (line.includes('GENERATED:END') && start > 0) {
-      out.push([start, i + 1]);
-      start = -1;
-    }
-  });
-  return out;
-}
-
-const files = new Map();
-let cur = null;
-for (const line of String(diff.stdout).split(/\n/)) {
-  const name = /^diff --git a\/(.+?) b\//.exec(line);
-  if (name) { cur = name[1]; if (!files.has(cur)) files.set(cur, []); continue; }
-  const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
-  if (hunk && cur) files.get(cur).push([Number(hunk[1]), hunk[2] === undefined ? 1 : Number(hunk[2])]);
-}
-
-let bad = 0;
-for (const rel of listed.stdout.split(/\n/).map((s) => s.trim()).filter(Boolean)) {
-  const norm = rel.split('\\').join('/');
-  const shown = spawnSync(git, ['show', `:${norm}`], { encoding: 'utf8' });
-  if (shown.status !== 0) {
-    console.error(`${norm}: 读不到暂存内容`);
-    bad += 1;
-    continue;
-  }
-  const text = shown.stdout;
-  const ranges = rangesOf(text);
-  if (!ranges.length) continue;
-  for (const [start, len] of files.get(norm) || []) {
-    const from = start;
-    const to = len === 0 ? start : start + len - 1;
-    if (!ranges.some(([s, e]) => !(to < s || from > e))) continue;
-    console.error(`${norm}: 暂存改动落入 GENERATED 区（${ranges.map(([s, e]) => `${s}-${e}`).join('、')}）。生成器重写时设 FLOW_KIT_ALLOW_GENERATED=1`);
-    bad += 1;
-    break;
-  }
-}
-process.exit(bad ? 1 : 0);

package/modules/gates/generated-readonly/local-pre-commit.line

@@ -1 +0,0 @@
-node .agents/hooks/check-generated.mjs

package/modules/gates/node-layer/README.md

@@ -1,9 +0,0 @@
-# node-layer
-
-暂存的 `src/**/*.{js,mjs,cjs,jsx,ts,tsx}` 不得 `import` / `require` `tests/`、`test/` 或 `__tests__/`。
-
-```sh
-npx agentic-flow-kit add-gate node-layer
-```
-
-装进 `.agents/hooks/` 后归项目所有。目录名或更多禁引路径直接改脚本里的判断。

package/modules/gates/node-layer/check-node-layer.mjs

@@ -1,29 +0,0 @@
-#!/usr/bin/env node
-// 暂存区内 src/ 下的脚本不得引用 tests/、test/ 或 __tests__/。
-// 正文只读索引（git show :path），不读工作区。
-import { spawnSync } from 'node:child_process';
-
-const git = process.platform === 'win32' ? 'git.exe' : 'git';
-const listed = spawnSync(git, ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' });
-if (listed.status !== 0) {
-  console.error('check-node-layer: git diff --cached 失败（需在 git 仓库的暂存区上运行）');
-  process.exit(1);
-}
-const re = /['"](?:[^'"]*\/)?(?:tests?|__tests__)(?:\/[^'"]*)?['"]/;
-let bad = 0;
-for (const rel of listed.stdout.split(/\n/).map((s) => s.trim()).filter(Boolean)) {
-  const norm = rel.split('\\').join('/');
-  if (!norm.startsWith('src/') || !/\.(?:[cm]?js|jsx|tsx?)$/.test(norm)) continue;
-  const shown = spawnSync(git, ['show', `:${norm}`], { encoding: 'utf8' });
-  if (shown.status !== 0) {
-    console.error(`${norm}: 读不到暂存内容`);
-    bad += 1;
-    continue;
-  }
-  shown.stdout.split(/\n/).forEach((line, i) => {
-    if (!re.test(line)) return;
-    console.error(`${norm}:${i + 1}: src 不得引用 tests/、test/ 或 __tests__/`);
-    bad += 1;
-  });
-}
-process.exit(bad ? 1 : 0);

package/modules/gates/node-layer/local-pre-commit.line

@@ -1 +0,0 @@
-node .agents/hooks/check-node-layer.mjs

package/modules/gates/py-import/README.md

@@ -1,9 +0,0 @@
-# py-import
-
-暂存的业务 `.py`（路径中不含 `tests/` 或 `test/`）不得出现行首 `import tests`、`from tests`、`import test`、`from test`。
-
-```sh
-npx agentic-flow-kit add-gate py-import
-```
-
-这是边界的一个窄实现。更细的分层用项目自己的 import linter，按 `modules/gates/README.md` 的平铺约定挂上。

package/modules/gates/py-import/check-py-import.mjs

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-// 暂存的业务 .py（不在 tests/ 或 test/ 下）不得 import tests 或 test。
-// 正文只读索引（git show :path），不读工作区。
-import { spawnSync } from 'node:child_process';
-
-const git = process.platform === 'win32' ? 'git.exe' : 'git';
-const listed = spawnSync(git, ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' });
-if (listed.status !== 0) {
-  console.error('check-py-import: git diff --cached 失败（需在 git 仓库的暂存区上运行）');
-  process.exit(1);
-}
-const re = /^\s*(?:import|from)\s+(?:tests?|test)\b/;
-let bad = 0;
-for (const rel of listed.stdout.split(/\n/).map((s) => s.trim()).filter(Boolean)) {
-  const norm = rel.split('\\').join('/');
-  if (!norm.endsWith('.py')) continue;
-  if (norm.split('/').some((seg) => seg === 'tests' || seg === 'test')) continue;
-  const shown = spawnSync(git, ['show', `:${norm}`], { encoding: 'utf8' });
-  if (shown.status !== 0) {
-    console.error(`${norm}: 读不到暂存内容`);
-    bad += 1;
-    continue;
-  }
-  shown.stdout.split(/\n/).forEach((line, i) => {
-    if (!re.test(line)) return;
-    console.error(`${norm}:${i + 1}: 业务代码不得 import tests 或 test`);
-    bad += 1;
-  });
-}
-process.exit(bad ? 1 : 0);

package/modules/gates/py-import/local-pre-commit.line

@@ -1 +0,0 @@
-node .agents/hooks/check-py-import.mjs

package/modules/gates/test-protect/README.md

@@ -1,23 +0,0 @@
-# test-protect
-
-暂存 diff 若同时包含「测试文件」与「非测试文件」（即测试与代码同框改动），提交失败。
-
-fix/调试任务中，测试是「bug 已修」的证据；证据与结论同一次改动 = 自证，闭环失去意义。此门禁把
-「fix 不得改测试」从提示语变成机器红线，不依赖 agent 客户端自觉。
-
-```sh
-npx agentic-flow-kit add-gate test-protect
-```
-
-**测试文件识别**（脚本头部 CONFIG 可按项目扩展）：
-
-- 目录面：`tests/`、`__tests__/`、`test/`、`spec/`（任意层级）
-- 文件面：`*.test.*`、`*.spec.*`、`_test_*.py`（python pytest 风格）
-
-**豁免**（不是漏洞，是显式语义）：
-
-- 纯测试提交（只改测试文件，无代码同框）——新增/修正测试本身合法。
-- 显式声明 `FLOW_KIT_ALLOW_TEST_EDIT=1 git commit`——对应 plan 中显式标注「本次需同步演进测试」
-  （测试先行 / 行为断言变更）。门禁只判暂存面事实，语义归显式声明，不读任务元数据。
-
-**不拦截**：merge 提交无暂存 diff；工作区未暂存改动（提交面之外）。

package/modules/gates/test-protect/check-test-protect.mjs

@@ -1,64 +0,0 @@
-#!/usr/bin/env node
-// test-protect — 防 agent 自证清白时弱化测试（2026-10-10 调研 P1 test-protect）。
-// 语义：fix/调试任务中，同一提交不得既改被测代码又改它的测试文件——测试是「bug 已修」的证据，
-//       证据与结论同一次改动 = 自证，闭环失去意义（Anthropic playbook Stage 4：fix 任务禁止改测试文件）。
-// 判定范围：本次提交的暂存 diff（git diff --cached --name-only），只拦「测试文件」与「非测试文件」同框出现。
-// 豁免：
-//   - 显式声明 `FLOW_KIT_ALLOW_TEST_EDIT=1 git commit`（对应 plan 中显式标注「本次需同步改测试」——测试先行、行为断言变更属于合法测试演进）。
-//   - 纯测试提交（只改测试文件，无被测代码同框）——新增/修正测试本身合法。
-//   - 测试文件自身之间的改动（如 fixture、helper 互改）。
-// 设计（对照调研 P1）：独立 add-gate 模块，不进 check-loop 核心检查面（20 项纪律）；pre-commit 挂载点走 local-pre-commit，
-//       不依赖 agent 客户端自觉。本脚本不读任务元数据（plan 状态 / frontmatter）——门禁只判暂存面事实，语义归环境变量显式声明。
-// 实现零依赖、纯 Node ≥18。
-
-import { spawnSync } from 'node:child_process';
-
-// 测试文件识别：常见测试目录/文件命名。装户可按项目在脚本头部 CONFIG 扩展。
-// 目录面：tests/、__tests__/、test/、spec/（仓库根或任意层级）；文件面：*.test.*、*.spec.*、_test.*（python pytest 风格）。
-const TEST_DIR_RE = /(^|\/)(tests?|__tests__|spec|test)\//i;
-const TEST_FILE_RE = /\.(test|spec)\.[^.]+$/i;
-const PYTEST_FILE_RE = /(^|\/)_?test_[^/]+\.py$/i;
-
-function isTestFile(rel) {
-  const n = rel.replace(/\\/g, '/');
-  if (TEST_DIR_RE.test(n)) return true;
-  if (TEST_FILE_RE.test(n)) return true;
-  if (PYTEST_FILE_RE.test(n)) return true;
-  return false;
-}
-
-function git(args, cwd) {
-  const p = spawnSync('git', args, { cwd, encoding: 'utf8' });
-  return { exit: p.status ?? 1, stdout: p.stdout || '', stderr: p.stderr || '' };
-}
-
-function main() {
-  const root = process.env.FLOW_KIT_GIT_ROOT || process.cwd();
-  // 只判暂存 diff（提交面）；工作区未暂存改动不拦（与 generated-readonly / node-layer 同口径：暂存面即提交意图）
-  const r = git(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], root);
-  if (r.exit !== 0) {
-    console.error('❌ test-protect：git diff --cached 失败（' + (r.stderr.trim() || '未知错误') + '）');
-    process.exit(1);
-  }
-  const files = r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
-  if (!files.length) return; // 无暂存改动（如 merge 提交）不拦
-
-  const tests = files.filter(isTestFile);
-  const nonTests = files.filter((f) => !isTestFile(f));
-  if (!tests.length || !nonTests.length) return; // 纯测试提交 / 纯代码提交都合法
-
-  if (process.env.FLOW_KIT_ALLOW_TEST_EDIT === '1') {
-    console.log('ℹ️  test-protect：FLOW_KIT_ALLOW_TEST_EDIT=1 显式放行（测试与代码同框改动）');
-    return;
-  }
-
-  const sample = tests.slice(0, 5).join('、') + (tests.length > 5 ? ` 等 ${tests.length} 个` : '');
-  const codeSample = nonTests.slice(0, 3).join('、') + (nonTests.length > 3 ? ` 等 ${nonTests.length} 个` : '');
-  console.error(`❌ test-protect：提交同时改动测试与代码——「测试文件」${sample} 与「非测试文件」${codeSample} 同框。`);
-  console.error('   fix/调试任务中，测试是 bug 已修的证据；证据与结论同一次改动 = 自证，闭环失去意义。');
-  console.error('   若本提交确实需要同步演进测试（测试先行 / 行为断言变更），显式声明后重试：');
-  console.error('     FLOW_KIT_ALLOW_TEST_EDIT=1 git commit');
-  process.exit(1);
-}
-
-main();

package/modules/gates/test-protect/local-pre-commit.line

@@ -1 +0,0 @@
-node .agents/hooks/check-test-protect.mjs

package/modules/hosts/README.md

@@ -1,57 +0,0 @@
-# 宿主适配层
-
-七个宿主的薄适配层。`flow-kit init --hosts <列表>` / `flow-kit add-host <宿主>` 把对应目录铺进装户仓，
-`sync` 随包升级。权威源是 `templates/_agents/{commands,roles}/*.md`，本目录是**纯转发薄层**——
-换宿主不换流程。
-
-## 约定
-
-每个宿主目录两子层：
-
-| 层 | 文件 | 说明 |
-|---|---|---|
-| `agents/` | `<角色>.md` | 角色契约薄适配（全宿主无前缀，文件名 = 权威源文件名） |
-| `commands/` | `<prefix><命令>.md` | 命令层薄适配，文件名统一带宿主前缀（见下），避免裸占宿主顶层命名空间 |
-
-`commandPrefix`（`src/profiles.mjs#HOSTS` 单源）：opencode / trae / claude / cursor / codex 用 `wf-`；
-zcode / omp 无该字段——只有角色层适配，不参与 commands 权威源映射。
-
-## 现有宿主
-
-| 宿主 | 装户目录 | commands 层 | 宿主怎么读 |
-|---|---|---|---|
-| `zcode` | `.zcode/` | 无（仅角色） | `.zcode/agents/*.md` |
-| `opencode` | `.opencode/` | `wf-*` | `.opencode/{agents,commands}/*.md` |
-| `trae` | `.trae/` | `wf-*` | `.trae/{agents,commands}/*.md` |
-| `omp` | `.omp/` | 无（仅角色） | `.omp/agents/*.md` |
-| `claude` | `.claude/` | `wf-*` | `.claude/commands` + `.claude/agents` |
-| `cursor` | `.cursor/` | `wf-*` | `.cursor/commands` |
-| `codex` | `.codex/` | `wf-*` | 仓库根 `AGENTS.md` + `.codex/skills/`；`.codex/commands` 是同形薄转发，供显式引用 |
-
-> codex 另有 `skills/` 子层（宿主级技能辅助），见 `modules/hosts/codex/skills/`。
-
-七个宿主一律入库（2026-10-05 起撤销 localOnly）——换宿主不丢文件、CI 克隆面一致。zcode 的会话级
-液态草稿（`.zcode/drafts/`、`.zcode/plans/`）是本机态、不该入库，init 不自动写这条规则，装户自行加进
-`.gitignore`。
-
-## 对账
-
-权威源改一处，要同步到 N 份薄适配——人工 grep 易漏：
-
-```bash
-flow-kit sync-hosts --diff     # 权威源 vs 薄适配漂移报告（默认，不改盘面）
-flow-kit sync-hosts --apply    # 单向同步：权威源 → 薄适配（不反向，避免污染权威源）
-```
-
-包源仓（含 `templates/_agents` + `modules/hosts`）与装户仓（含 `.agents`）两种布局都可用——
-同一命令两处口径一致。装户侧等价体检在 `flow-kit doctor`（跨宿主薄适配正文段漂移校验）。
-
-## 加一个新宿主
-
-1. 在 `src/profiles.mjs#HOSTS` 注册：`dir`（装户目录名，带点）、`commandPrefix`（有命令层才填）。
-2. 建 `modules/hosts/<宿主>/`：`agents/*.md` 三角色薄适配（从现有宿主拷一份改 frontmatter/调用约定）；
-   有命令层再加 `commands/<prefix>*.md`。
-3. 权威源（`templates/_agents/{commands,roles}/`）不动——薄适配只转发，不复刻判据。
-4. 跑 `flow-kit sync-hosts --diff` 自查新增薄适配与权威源对齐；`npm test`（含 sync-hosts 套件与
-   doctor 跨宿主校验回归）。
-5. README「现有宿主」表与 `cli.mjs` HELP 的宿主清单随动。