agentic-flow-kit 1.8.7 → 2.1.0

package/templates/scaffold/workflow/artifact-sources.md

@@ -0,0 +1,25 @@
+# 工件真相源（Source of Truth）
+
+> 背景（Anthropic AI-native SDLC）：每个工件必须指定**唯一**真相源，其他系统只存副本或链接。
+> 否则 Jira / Confluence / Figma / 变更单与仓库文档会互相漂移，agent 会读到两份“真相”。
+>
+> 用法：开工前查本表；新增工件类型必须先登记。没有登记的工件，默认以仓库 markdown 为准。
+
+| 工件 | 唯一真相源 | 其他系统怎么放 | 谁维护 | 过期信号 |
+|---|---|---|---|---|
+| intent（要什么） | `workflow/intents/` markdown | Jira/需求工具存链接 + 摘要；评审记录在链接里 | 产品 owner | 状态仍 draft 超过约定天数 |
+| spec（决定什么） | `workflow/specs/` markdown | Confluence 只放链接，不复制正文 | 产品 + 技术 lead | 与 intent 的验收判据不一致 |
+| plan（怎么做） | `workflow/plans/` markdown | PR 描述引用路径；不另写一份 | 实现者 | 合并 diff 与 plan 文件清单不一致 |
+| 代码与测试 | git 仓库 | 任何外部系统只读镜像 | 工程 | 镜像落后一个提交 |
+| 评审结论 | PR / `workflow/reviews.d/` | 评审工具存链接或事件 id | 复核者 | 意见无采纳/拒绝结论 |
+| 事故与复盘 | `workflow/incidents/` | 事故平台存链接 + 影响面摘要 | on-call + owner | 复盘三件套缺一 |
+| 领域知识 | `wiki/` markdown | `wiki/` HTML 只是展示快照 | wiki owner | HTML 与 md 不一致 |
+| 记忆主张 | `workflow/claims.d/` | 不复制；其他文档引用 claim id | 主智能体 | 引用的原文已消失（broken） |
+| 行为评测 | `.agents/evals/results.jsonl` | CI 报告存链接 | 平台/引擎 owner | 凭证过期或签名不匹配 |
+
+## 迁移到 AI-native 时
+
+1. 先逐项填本表，再动流程；没有“唯一源”的工件不要开始自动化。
+2. 旧系统（Jira/Figma/变更委员会）不能立刻下线时，**仓库为源、旧系统为链接**，并在旧系统字段里写清“以 commit/path 为准”。
+3. 反向选择（旧系统为源）只有在审计/监管强制时才用；此时仓库文档必须带 `source: <系统>#<id>`，且不复制正文。
+4. 任何“两份都像真的”状态都按缺陷处理，登记 papercut。

package/templates/scaffold/workflow/delegations.md

@@ -0,0 +1,4 @@
+# 委派台账月度快照（生成物，勿手改）
+
+> 由 `node .agents/scripts/agg-delegations.mjs --write` 重生成。
+> 新装户占位；首次生成后自动填充。

package/templates/scaffold/workflow/effective-policy.md

@@ -0,0 +1,4 @@
+# 生效策略快照（生成物，勿手改）
+
+> 由 `node .agents/scripts/gen-effective-policy.mjs` 重生成。
+> 新装户占位；锚表与生效策略在首次生成后自动填充。

package/templates/scaffold/workflow/gate-cost.md

@@ -0,0 +1,4 @@
+# 门禁成本近窗快照（生成物，勿手改）
+
+> 由 `node .agents/scripts/gen-workflow-metrics.mjs --gate-cost-only` 重生成。
+> 新装户占位；首次生成后自动填充近窗门禁耗时。

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

@@ -0,0 +1,49 @@
+---
+状态: open
+级别: L1
+发现: YYYY-MM-DD
+来源: <self | user | test | monitor——谁发现，见 .agents/config/workflow-enums.txt incident.source.all>
+影响环境: <dev | staging | prod | none——缺陷触达的环境，none=未触达运行环境>
+模块: <词表之一，见 .agents/config/workflow-modules.txt>
+---
+# INCIDENT — <日期 主题>
+<!-- 复制为 YYYY-MM-DD-<主题>.md；线上或实测发现的功能缺陷都记录，历史 BUG 可回填 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈open/fixed/closed（严格枚举，附注写备注键）；级别∈L1/L2/L3；闭环引擎启用前的回填件加一行 `流程: legacy`（豁免级别/配对检查）；正文不再写状态/级别/发现行 -->
+<!-- 归因两键（2026-10-11 incident-attribution 起新建件必填，check-loop 检查 24 校验）：锚前存量不回填；「来源」是缺陷发现方（供来源×环境交叉表机器复算，替代逐件人工判读），「影响环境」写实际触达环境（未触达写 none） -->
+
+## 时间线
+- <发现 → 定位 → 止血 → 恢复，带时刻>
+- 用户确认：草稿过目通过（<日期>）
+<!-- 上行是**L2/L3 起草 spec 的机器前置**（fill-spec / confirm-doc 校验）：须为「时间线」小节内的行首条目；
+     接受形态 `- 用户确认：…` / `- **用户确认**：…` / `- <日期> 用户确认：…`（词前词后加粗、日期前缀均可）；
+     正文叙述句（如「用户确认了方案」）不算留痕。形态清单写在本注释内，避免样例行自含描述文字 -->
+
+## 影响面
+- <页面 / 接口 / 数据范围>
+
+## 根因
+<一句话；深层原因另起一行>
+
+## 为什么之前没拦住
+<门禁 / 测试 / 规范各查一遍：哪一层本可以拦住>
+
+## 复盘三件套（缺一不可）
+
+> 目的：让事故真正回到 Plan，不让「防复发」承诺停留在文档里。模块已逐步上线，事故可能来自 dev / staging / prod 任一环境。
+
+1. 结构性修复
+   - 修复 commit：<SHA + 改动文件清单>
+   - 影响环境：dev / staging / prod（已上线模块若波及 prod，需附影响用户数 / 持续时长 / 是否回滚）
+   - 是否需要新 intent：
+     - 是 → ../intents/YYYY-MM-DD-<主题>.md（根因属「门禁缺位 / 规范未落地 / 系统性问题」时强制立，即使结构性修复已完成）
+     - 否 → 理由：<根因属实现 bug、单点修复已完成，且已有规范条目覆盖>
+
+2. 防复发验证（必须落到自动化用例或回归清单条目，禁止只写「已人工验证」）
+   - 自动化用例：tests/<测试文件>（<用例名 / 数量>）
+   - 或 test 步骤：.agents/commands/stages.md Test 章 + <具体操作>
+   - 或回归清单条目：workflow/regression-checklist.md（防复发验证节追加一行）
+
+3. 规范条目（必须有可追溯的落点）
+   - 落点（多选）：AGENTS.md <章节> / .agents/hooks/<脚本> / .agents/skills/<skill> / .agents/commands/<cmd> / 回归清单 §<章节>
+   - 引用：commit <SHA> / 文件:<路径>#L<行>
+   - 若无新增条目，理由：<已有条目覆盖，说明条目位置>

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

@@ -0,0 +1,43 @@
+---
+状态: draft
+级别: L1
+日期: YYYY-MM-DD
+模块: <词表之一，见 .agents/config/workflow-modules.txt>
+备注: <可选：附注自由文本，check-loop 不解析>
+---
+# INTENT — <主题>
+<!-- 复制本模板为 YYYY-MM-DD-<主题>.md 后填写；plans/ 下同名文件与本文件配对 -->
+<!-- frontmatter 受限子集（2026-09-13）：每行 `键: 值`；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L1/L2/L3；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->
+
+## 背景与问题
+<为什么做；写明需求来源（工单 / 沟通记录 / 待办事项）>
+
+## 目标
+- <可验证的目标>
+
+## 非目标（L1 微改动无实质内容可删本节，不硬填）
+- <明确不做的，防止范围蔓延>
+
+## 约束（L1 微改动无实质内容可删本节，不硬填）
+- <复用什么、不许动什么>
+
+## 影响面
+- 模块：shared / material（Domain / Application / Infrastructure / API）
+- 数据库：无 / <表名>（涉及 schema 变更 → L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 `.agents/commands/new-task.md` §级别判断）
+- 前端页面：<路由或组件，无则删本行>
+
+## 触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 中说明）
+- [ ] Application 禁引 Infrastructure / DbContext（豁免仅限分类树原生 LINQ）
+- [ ] 编码生成逻辑（FormulaEngine / CategoryPrefix）→ 级别至少 L2
+- [ ] 跨调用方契约变更（共享层基类 / DTO 形状 / 接口签名 / 既有参数语义 / 全局响应与分页校验口径）→ 级别至少 L2
+- [ ] schema / 迁移 SQL / DI 链 → 级别 L3
+- [ ] 前端：Drawer 一律 / 禁 a-select 大数据量 / 样式统一 style.css
+
+> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。
+
+## 验收标准（可测试）
+<!-- 每条加稳定编号 A1..An（锚 coverageSince 2026-10-22 起，spec 确认门按编号查覆盖）；增删用新号、不复用旧号。 -->
+- [ ] A1 <逐条可测试；写不出可测试判据 = 还没想清楚>
+
+> **闭环对账**：关单在 test 阶段（不依赖 deploy）。intent 置 done 前逐条勾验，每条勾选项后补证据——`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟脚本输出>）`。
+> done 状态仍有未勾项会被 check-loop 拦截（2026-09-12 起新建 intent 为 hard-block，存量 intent 仅 warning 提示）；勾选但缺「证据：」为 warning。

package/templates/scaffold/workflow/metrics.md

@@ -0,0 +1,4 @@
+# workflow metrics（生成物，勿手改）
+
+> 由 `node .agents/scripts/gen-workflow-metrics.mjs` 从台账与文档树重生成。
+> 新装户占位；首次生成后自动填充月度指标。

package/templates/scaffold/workflow/non-engineer-intent.md

@@ -0,0 +1,51 @@
+# 非工程角色：写一份 intent
+
+> 目标：产品 / 业务 / 运营不需要 git 或命令行，也能产出下一阶段能直接读的 `intent.md`。
+> 产出的文件仍以仓库为真相源；本文只负责“怎么进来”。
+
+## 最简路径（claude.ai / Cowork）
+
+1. 在会话里用自己的话描述：**谁遇到了什么问题、现在不能做什么、什么算变好、什么不在范围内**。不需要正式格式。
+2. 让 Claude 按下面模板写成 `intent.md`；它会补问范围、用户、约束、成功判据。
+3. 你逐条纠正它理解错的地方。**作者与时间**必须保留。
+4. 让 Claude 通过 GitHub 连接器把文件提交到仓库的 `workflow/intents/<英文-kebab>.md`。
+   不会 git 也没关系：连接器负责提交；你只需要确认文件名与内容。
+5. 产品 owner 在仓库里把状态从 `draft` 改为 `approved`（或打回）。
+
+## 模板
+
+```md
+# Intent: <一句话标题>
+Author: <姓名/角色>  Status: draft
+Date: <YYYY-MM-DD>
+
+## 问题
+<谁、在什么场景、现在不能做什么；有数字更好>
+
+## 期望结果
+<可观察的“变好”是什么>
+
+## 受影响的人与系统
+<用户/岗位/模块/接口>
+
+## 约束
+<不能新增 PII、必须复用现有认证、上线窗口……>
+
+## 非目标
+<明确不做什么，防止范围蔓延>
+
+## 开放问题
+<需要谁拍板；没有写“无”>
+```
+
+## 红线
+
+- 不写实现方案（那是 spec/plan 的事）；只写要什么、为什么、约束。
+- 不在 intent 里贴密钥、真实用户数据或内部链接凭据。
+- 状态只能由产品 owner 改；agent 不自行把 draft 改成 approved。
+- 一个 intent 只解决一个问题；拆得开就拆。
+
+## 技术侧配合
+
+- 仓库里跑 `node .agents/scripts/fill-intent.mjs` 可生成骨架（有引擎时）。
+- 进入 Design 前，产品 owner 必须回答 open questions 或明确“带问进入”。

package/templates/scaffold/workflow/papercuts.md

@@ -0,0 +1,3 @@
+# Papercuts 清单
+
+> 手工维护：记录高频小痛点与处置状态。格式与条目协议见 `workflow/README.md`。

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

@@ -0,0 +1,47 @@
+---
+状态: draft
+级别: L1
+日期: <YYYY-MM-DD 建档日>
+模块: <词表之一，见 .agents/config/workflow-modules.txt>
+---
+# PLAN — <与入口文档同名主题>
+<!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2/L3 必须先有 ../specs/ 同名 spec 确认通过；AI 起草、用户对话内确认后开工 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L1/L2/L3；正文不再写状态/级别行 -->
+<!-- L1（2026-10-10）：新单用 fill-plan.mjs --level L1，本文件即入口，不另立 intent。节：入口 / 改动方案 / 约束与风险 / 验证计划 / 验收标准。下面保留的「改动面 / 验证方式」是存量极简形态，新单不要再复制这两节标题。 -->
+<!-- 模糊点纪律（2026-10-16）：起草/修订遇无法自行决策的模糊点（多种解释/口径缺失/依赖外部事实）禁止脑补——在对应节原地插入 [NEEDS CLARIFICATION]: <一句话问题> 并保持 draft 向用户求澄清；澄清后删除标记、把决策落为正文。approved 前标记须清零（口径见 workflow/README.md 文档协议「模糊点显式阻断」）。 -->
+
+对应入口：L1 = 本 plan。修复类另保留 ../incidents/YYYY-MM-DD-<主题>.md。L2/L3 = ../intents/YYYY-MM-DD-<主题>.md
+对应 spec：../specs/YYYY-MM-DD-<主题>.md（仅 L2/L3）
+
+## 改动面（L1 极简形态主节；L2/L3 可作任务拆解的汇总或删本节）
+- <文件/组件>：<做什么；判据细节直接写进条目，如「L771 message.success 改『更新成功』」>
+<!-- stages.md Build §2 确认的改动清单确认后回填本节落盘（对话留痕仅供当次）——改动面 + 任务勾选态 + git status = 会话重入三锚（2026-10-11 session-context） -->
+
+## 任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）
+<!-- 任务即勾选态（2026-10-11 session-context）：完成一项立刻勾选并回填留痕；压缩 / 新会话续作先读本表勾选态 + git status 重建进度，禁凭记忆补勾 -->
+<!-- 依赖行（blocking edges，matt to-tickets 同构）：显式声明阻塞关系后「依赖行所指任务已勾选」即可开工——无未决阻塞的任务集 = frontier，可并行派发（多 worktree / 委派「新开+合并范围」）；纯顺序链依赖行退化为「任务 N-1」，零额外成本 -->
+- [ ] 1. <任务>
+   - 判据：<怎样算完成；尽量对应一个测试或可复现操作>
+   - 依赖：无（可立即开工）/ 被任务 <N> 阻塞
+   - 风险：低 / 中 / 高（<原因>）
+   - 留痕：（勾选时回填 commit SHA / 测试名 / 实测输出）
+- [ ] 2. <任务>
+   - 判据：…
+   - 依赖：…
+   - 风险：…
+   - 留痕：…
+
+## 执行顺序（L2/L3 必填；L1 单文件微改动删本节）
+<1 → 2 → 3；依赖已在上表「依赖」行显式化时本节只写一句「见任务拆解依赖行，frontier = 无未决阻塞任务」，纯顺序链写 1 → N 即可>
+
+## 验证方式
+- 构建：<项目构建命令>（+ <测试命令>）
+- 前端：cd frontend && npm run build（vue-tsc）
+- UI：.agents/commands/stages.md Test 章（涉及页面改动必走，headless Chrome 实测）
+- L2 追加：<契约 / 规则面比对：编码结果抽样 / 接口契约断言 / 口径对账>
+- L3 追加：<含 schema 变更：备份 + 回滚 SQL 就绪后执行；仅运行时 / 管线：回退上一 release tag + 配置开关预案>
+
+## 确认与复核
+> 确认 = 用户在对话内一句话通过；确认后本 plan 状态 `draft → approved` 并回填本节（确认环节的机器可见态），`done` 只在关单出现——禁从 `draft` 直跳 `done`（2026-09-22 papercut）。
+- 确认结果：approved（YYYY-MM-DD 用户对话内确认）；done（YYYY-MM-DD 关单，随入口文档置终态）
+- 确认门记录：plan 草稿全文过目 + 改动清单确认（`stages.md` Build 两道门，逐次，不合并）

package/templates/scaffold/workflow/regression-checklist.md

@@ -0,0 +1,3 @@
+# 回归清单
+
+> 手工维护：关键路径与防复发验证项。新增条目须关联 incident 或 plan。

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/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` 的生成区已经带这对标记。