agentic-flow-kit 0.2.0

package/templates/_githooks/pre-commit

@@ -0,0 +1,58 @@
+#!/bin/sh
+# Git 原生 pre-commit hook（经 core.hooksPath 挂载，git 执行、不依赖 agent 客户端）— agentic-flow-kit 通用编排
+# 通用门禁序：闭环配对(增量) → wiki 台账(增量) → 常驻面体积预算(增量) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs)
+# 项目专属门禁（架构红线/业务守卫等）放 .agents/hooks/local-pre-commit——存在即在本钩子内执行，返回非零即阻断提交
+# 合并提交场景由 .githooks/pre-merge-commit 原样转发到本脚本（合并时 git 调的是 pre-merge-commit，
+# 不是 pre-commit）——门禁清单只此一份，避免两处分叉
+
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+# run_gate <标签> <脚本> [参数...]：sh 优先、无 sh 用 bash；非零即阻断
+run_gate() {
+  gate_label="$1"; shift
+  if command -v sh >/dev/null 2>&1; then sh "$@"; else bash "$@"; fi
+  rc=$?
+  if [ $rc -ne 0 ]; then
+    echo "pre-commit: $gate_label 未通过，提交已阻止" >&2
+    exit $rc
+  fi
+}
+
+# 闭环配对门禁（增量版，check-pairing-incremental.sh：本次暂存的 intents/incidents 入口须已有同名 plan）
+run_gate "闭环配对（增量）" .agents/hooks/check-pairing-incremental.sh
+
+# wiki 台账门禁（增量，check-wiki-ledger.sh：暂存区触及 wiki/ 时跑 verify-wiki-consistency 三方一致性；
+# 无 wiki/ 变更即跳过）
+run_gate "wiki 台账（增量）" .agents/hooks/check-wiki-ledger.sh
+
+# 常驻面体积预算（增量硬拦，rule-budget.sh --staged：只查本次暂存触及的条目与触及目录的合计；
+# 超限即阻断——常驻面只增不减，须先删除或下沉一条被取代条目再增）
+if [ -f .agents/scripts/rule-budget.sh ] && [ -f .agents/rule-budgets.txt ]; then
+  run_gate "常驻面体积预算" .agents/scripts/rule-budget.sh --staged
+fi
+
+# 项目门禁挂载点：.agents/hooks/local-pre-commit（项目自建门禁/门禁模块接线处，存在即执行）
+if [ -f .agents/hooks/local-pre-commit ]; then
+  run_gate "项目门禁（local-pre-commit）" .agents/hooks/local-pre-commit
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "pre-commit: 未找到 node——敏感信息扫描与条件构建无法执行，提交已阻止（安装 Node.js 后重试）" >&2
+  exit 1
+fi
+
+# 合并提交 → 构建验证覆盖【完整合并树】，不做按扩展名的条件裁剪。
+# 两条路径：`git merge` 自动提交由 .githooks/pre-merge-commit 显式传 `--full` 转发到本脚本；
+# 冲突解决后手动 `git commit` 由 git 直接调本脚本，此处按 MERGE_HEAD 探测补上（此时合并仍在进行）。
+full_args="$*"
+if [ -z "$full_args" ] && git rev-parse -q --verify MERGE_HEAD >/dev/null 2>&1; then
+  full_args=--full
+fi
+
+node .agents/hooks/commit-check.cjs $full_args
+rc=$?
+if [ $rc -ne 0 ]; then
+  echo "pre-commit: 验证未通过，提交已阻止" >&2
+  exit $rc
+fi
+exit 0

package/templates/_githooks/pre-merge-commit

@@ -0,0 +1,24 @@
+#!/bin/sh
+# Git 原生 pre-merge-commit hook（经 core.hooksPath 挂载，git 执行、不依赖 agent 客户端）
+#
+# 背景：git 对 `git merge` 调的是**本钩子**，不是 pre-commit。此前仓库只挂了
+# pre-commit / pre-push / commit-msg，故合并提交绕过全部门禁、未经任何校验直接落库
+# （2026-09-19 实测，见 workflow/papercuts.md 同日行——那次合并带入后端 .cs 改动，
+# 靠人工补跑静态门 + 全量测试才覆盖到）。
+#
+# 做法：转发到 .githooks/pre-commit（门禁清单只此一份，避免两份拷贝日后分叉），
+# 并显式传 `--full`——本钩子「只对 merge 触发」这一身份就是最强信号，无需再去探测
+# MERGE_HEAD（2026-09-19 实测：本时点 MERGE_HEAD 已不可靠）。`--full` 令编译验证
+# 覆盖【完整合并树】、不按扩展名条件裁剪：合并结果是没人验证过的新状态，且其 diff
+# 相对第一父，裁剪会漏掉需要重跑的一侧。
+#
+# 冲突解决后手动 `git commit` 走的是 pre-commit 自身，那条路径由 pre-commit 内部的
+# MERGE_HEAD 探测覆盖（此时合并仍在进行，MERGE_HEAD 确定存在）。
+
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+if command -v sh >/dev/null 2>&1; then
+  exec sh .githooks/pre-commit --full
+else
+  exec bash .githooks/pre-commit --full
+fi

package/templates/_githooks/pre-push

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发）
+# 跑 .agents/scripts/check-loop.sh：扫 workflow/ 闭环骨架断档
+#   - 硬阻断（exit 1）= 配对断裂 / 回路断档 → push 立即阻断
+#   - 警告（advisory）= 状态未确认 / 模板占位残留 / 引用漂移 等卫生项 → 仅打印提示
+#
+# 机器门：本地钩子（唯一本地机器门）——CI 配置为本地未入库件（.gitignore 排除），不构成跨环境保证。
+# 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
+
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+# 读 stdin（pre-push 协议要求消费 stdin：本地 ref + 远端 ref + sha x2 每行）
+while read -r _ _ _ _; do :; done
+
+SCRIPT=".agents/scripts/check-loop.sh"
+if [ ! -f "$SCRIPT" ]; then
+  echo "pre-push: 未找到 $SCRIPT，跳过闭环扫描" >&2
+  exit 0
+fi
+
+# Windows 下 git 自带 bash 能直接执行 sh 脚本；其它环境 sh 兼容
+if command -v sh >/dev/null 2>&1; then
+  sh "$SCRIPT"
+else
+  bash "$SCRIPT"
+fi
+rc=$?
+if [ $rc -ne 0 ]; then
+  echo "pre-push: 闭环骨架断档（hard-block）未通过，push 已阻断。修 workflow 文档后重推——不要用 --no-verify 绕过（CI 服务端会再次兜底拦截）" >&2
+  exit $rc
+fi
+exit 0

package/templates/wiki/INDEX.md

@@ -0,0 +1,23 @@
+# Wiki 索引
+
+> 本目录为整理后的项目知识沉淀，按主题归位。原文档归档到 `drafts-archive/`（按 `日期-主题` 命名）。
+> 人工只维护两样：**磁盘文件本身 + 下方速览表「用途」列**；速览计数 / 合计行 / 映射表 / 看板 DATA 均为生成区，勿手改——重生成 `node .agents/scripts/gen-wiki-board.mjs`（一致性验证 `node .agents/scripts/verify-wiki-consistency.mjs`）。
+>
+> 看板：`知识沉淀总览.html`（同级目录）。
+
+## 主题目录速览
+
+| 主题 | 文件数 | 用途 |
+|---|---|---|
+
+合计：**0 份**知识文档，**0 个主题**
+
+## 文件 → 主题 → 归属目录 映射表
+
+（生成区：gen-wiki-board.mjs 维护）
+
+## 命名规则
+
+- 主题目录用中文名（如 `产品需求/`、`开发方案/`、`测试报告/`、`项目规范/`）；文件名不限中英文。
+- 成套产物（md+html 对）整目录计入索引与看板。
+- 原始/一次性文档归档 `drafts-archive/<日期-主题>/`，只读不增量。

package/templates/wiki/drafts-archive/README.md

@@ -0,0 +1,3 @@
+# drafts-archive — 原文档归档区
+
+按 `<日期-主题>/` 分目录存放整理前的原始文档快照，**只读不增量**：wiki 主题目录是活知识层，本区只留历史证据。归档文件不参与 INDEX 三方比对的文件级登记，仅计入归档总数（见 `../知识沉淀总览.html` 的 summary.archive）。

package/templates/wiki//347/237/245/350/257/206/346/262/211/346/267/200/346/200/273/350/247/210.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<title>知识沉淀总览</title>
+<style>
+  body{font-family:system-ui,'Segoe UI','Microsoft YaHei',sans-serif;max-width:1100px;margin:2rem auto;padding:0 1rem;color:#222}
+  h1{border-bottom:2px solid #ddd;padding-bottom:.4rem}
+  table{border-collapse:collapse;width:100%;margin:1rem 0}
+  td,th{border:1px solid #ddd;padding:.4rem .6rem;text-align:left;vertical-align:top}
+  th{background:#f6f6f6}
+  a{color:#0366d6;text-decoration:none}
+  a:hover{text-decoration:underline}
+  .muted{color:#888;font-size:.9em}
+</style>
+</head>
+<body>
+<h1>知识沉淀总览</h1>
+<p class="muted">生成物：<code>node .agents/scripts/gen-wiki-board.mjs</code> 重生成（人工只维护 wiki/INDEX.md 速览表「用途」列与磁盘文件本身）。</p>
+<div id="app"></div>
+<script>
+const DATA = {
+  "summary": { "total": 0, "topics": 0, "files": 0, "archive": 0 },
+  "topics": [
+  ]
+};
+(function () {
+  var el = document.getElementById('app');
+  var p = document.createElement('p');
+  p.textContent = '合计 ' + DATA.summary.files + ' 份知识文档 / ' + DATA.summary.topics + ' 个主题 / 归档 ' + DATA.summary.archive + ' 份';
+  el.appendChild(p);
+  var table = document.createElement('table');
+  var head = document.createElement('tr');
+  ['主题', '文件'].forEach(function (h) {
+    var th = document.createElement('th'); th.textContent = h; head.appendChild(th);
+  });
+  table.appendChild(head);
+  DATA.topics.forEach(function (t) {
+    var tr = document.createElement('tr');
+    var td1 = document.createElement('td'); td1.textContent = t.name; tr.appendChild(td1);
+    var td2 = document.createElement('td');
+    t.files.forEach(function (f, i) {
+      if (i) td2.appendChild(document.createElement('br'));
+      var a = document.createElement('a');
+      a.setAttribute('href', f.dir + f.file);
+      a.textContent = f.file;
+      td2.appendChild(a);
+    });
+    tr.appendChild(td2);
+    table.appendChild(tr);
+  });
+  el.appendChild(table);
+})();
+</script>
+</body>
+</html>

package/templates/workflow/README.md

@@ -0,0 +1,52 @@
+# workflow — AI 驱动闭环流程（唯一真相源）
+
+本目录是个人 AI 工作流引擎的唯一载体：**intents（为什么做）→ specs（怎么设计）→ plans（怎么做）→ incidents（学到了什么）**。单人 + AI 协作：唯一决策人与授权人是用户本人，多人评审暂缓，确认都在对话内一句话完成，追溯靠 git（commit + release tag）。
+
+> 闭环新增记录一律写在本目录。
+
+## 目录结构
+
+| 目录 | 放什么 | 命名 |
+|------|--------|------|
+| `intents/` | 意图文档：背景、目标/非目标、验收标准、级别、触达红线 | `YYYY-MM-DD-<主题>.md` |
+| `specs/` | 设计规格：功能行为、数据流、系统改动、约束遵守映射 | 与入口文档（intent / incident）同名 |
+| `plans/` | 计划文档：与入口文档同名配对，任务拆解 + 判据 + 风险 | 与入口文档（intent / incident）同名 |
+| `incidents/` | 事故复盘：时间线、根因、为什么没拦住、复盘三件套 | `YYYY-MM-DD-<主题>.md` |
+
+**命名一律英文 kebab-case**（如 `2026-09-07-<主题>.md`），**禁中文文件名**——check-loop 对非 ASCII 文件名给 warning。文档内容（标题/正文）不受此限。
+
+**文档协议（frontmatter 受限子集）**：四类文档头部一律为 YAML frontmatter（每行 `键: 值`，机器字段唯一来源）——`状态`（intent/spec/plan：draft/approved/done/superseded/cancelled；incident：open/fixed/closed，**严格枚举**，附注写 `备注:` 键）、`级别`（L0-L3）、`日期`/`发现`（YYYY-MM-DD）、`模块`（**新建文档必填**，取值见 `.agents/workflow-modules.txt` 词表，单值取主导模块；存量不回填，AI 触碰时顺手补）、L3 spec 的 `确认结果`/`确认时间`、回填件 `流程: legacy`。**`状态` 迁移须经 `approved`**（确认环节的机器可见态，`done` 只在关单出现）：新建的 spec/plan 若已 done 而 git 历史中从未出现行首 `状态: approved`，check-loop 报「确认态缺失」warning。check-loop 只扫 frontmatter 取机器字段（`fm_get` 字段断言），正文不再写「状态：/级别：」行；叙述性字段（独立复核/复盘三件套/验收勾验）仍留正文按节锚定。
+
+各子目录内 `_TEMPLATE.md` 为起步模板，复制后填写，不直接改动模板本身。
+
+根目录 `regression-checklist.md` 为**活文档回归清单**：deploy 回归必过条目与 incident 防复发验证的统一落点，随模块上线补充、随 incident 追加。
+
+## 使用方式
+
+- **发起新任务**：执行 `.agents/commands/new-task.md` 定义的流程（6 阶段总入口）
+- **看板**：任务入口幂等拉起 .agents/scripts/ensure-board.ps1（探活 / 旧代码自动重启 / 全新启动弹浏览器），服务只起不关，实时只读 http://127.0.0.1:{{BOARD_PORT}}；**预警层，非门禁；告警口径对齐 check-loop 硬断档**。端口被占用时先探活 `/api/board`——响应不含 `cards` 即判为他人进程，打印 pid / 进程名并退出，不 kill
+- **检索**：活跃流程读 `INDEX.md`（生成物，`node .agents/scripts/gen-workflow-index.mjs` 重生成、`--check` 校验漂移）；跨语料检索 `node .agents/scripts/kb-search.mjs "<词>"`（workflow 按节级定位 + wiki 全文，`--type/--module/--status/-n` 过滤；`--status all` 显式全量）
+- **验证**：`.agents/commands/test.md`（静态门 + 实测；项目自有验证脚本/门禁如有，见 `.agents/hooks/local-pre-commit` 与 test.md 项目适配区）
+- **评审**：`.agents/commands/review.md`（按 P0 / P1 / P2 分级：机器兜底 + AI 自查出清单，用户决策定性与合入）
+- **上线**：`.agents/commands/deploy.md`（上线前必跑清单）
+- **量化**：委派/自做结果记 `delegations.md`，聚合跑 `node .agents/scripts/agg-delegations.cjs`（**并发扩容门槛见该文件——数字达标前不扩并发**）；语料与常驻面体积的**月度快照**跑 `node .agents/scripts/gen-workflow-metrics.mjs`（每月一行落 `metrics.md`，同月重跑即更新；明细看 stdout）
+- **追溯**：git 即审计——文档随代码同 commit、上线打 `release/<日期>` tag，`git log` 全链路可查；多人评审暂缓，git 历史即评审记录
+- **级别**：L0 例行 ｜ L1 实现级（页面 / 交互 / 样式等，未命中 L2/L3）｜ L2 规则 / 契约（编码权威 / 共享契约 / 既有接口语义 / 全局横切口径，触达面闭集见 `.agents/commands/new-task.md` §级别判断）｜ L3 数据与运行时结构（schema / 迁移 SQL / DI 链 / 认证与中间件管线）；混合改动就高不就低
+
+## 执行模型
+
+- 默认宿主主智能体负责阶段路由、用户确认、关键判断和最终验收，不注册为额外角色。
+- 阶段命令仅在边界明确时委派 `.agents/roles/implementer.md`、`.agents/roles/independent-reviewer.md`、`.agents/roles/ui-verifier.md`。
+- 各 agent 宿主（OpenCode / Trae / ZCode 等）通过其适配目录（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）下的薄 Adapter 注册角色；角色行为只维护在 `.agents/roles/`。
+- 宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行；L2 / L3 独立复核不得回退为原主智能体自查。
+- 子智能体不得跨越用户确认门，也不得自行提交、合入或上线；所有结果由主智能体复核后交用户决策。
+
+## 闭环规则
+
+1. L1 以上新需求始于已确认的 intent；L1 以上修复始于已确认的 incident 草稿（作为 intent 等价入口）
+2. L2 / L3 变更必须先有与入口文档同名的 spec 确认通过（L3 加新会话独立复核），方可起草 plan；L1 用极简 plan——改动面 + 验证方式两节起步，多文件多步骤再加任务拆解/执行顺序
+3. 实现产物必须通过静态门（构建 + 测试 + 项目门禁）
+4. 线上 / 实测缺陷回落到 `incidents/`，复盘三件套（新 intent、防复发验证、规范条目）缺一不可；**根因属「门禁缺位 / 规范未落地 / 系统性问题」时，即使结构性修复已完成也必须立新 intent** 追踪系统性改进，禁止以「修复已完成」为由绕过 intent 回路
+5. 关单在 test：逐条勾验入口文档「验收标准」并补证据后 intent → done（不依赖是否上 prod）。done 仍有未勾项会被 check-loop 拦（新建 intent hard-block）。上 prod 另走 deploy（tag / 回滚 / 观察）
+6. 放弃留档：方案曾确认后不做 → `superseded`；未完成即取消 → `cancelled`。二者均为已确认终态，check-loop 不按「状态未确认」拦截；L3 放弃件豁免「确认结果必须为 approved」
+7. 后续回归清单与周检清单也归档本目录

package/templates/workflow/delegations.md

@@ -0,0 +1,28 @@
+# 量化证据台账（委派 + 自做任务）
+
+> 目的：把「一次完成率 / 平均返工次数 / 主兜底占比 / 月度故障数」从感觉变成数字——**数字达标之前不扩并发**（门槛见 §并发扩容门槛）。
+> 记法（主智能体顺手写一行，不增加用户负担）：
+> - **委派结果表**：每次向子智能体/执行模型委派后追加一行。
+> - **自做任务结果表**：主智能体自己完成的 **L1+ 新需求任务**，闭环时（intent→done）追加一行；**修复类不重复记**——incident 本身即故障信号，聚合脚本按月扫 `workflow/incidents/` 计数。
+> - 结果列取值：`一次通过`（静态门首跑全过且复核无 P0/P1 返工）/ `返工×N`（回炉 N 次）/ `主兜底`（executor 失败、主智能体接手——委派口径专用，计返工信号）/ `返工待修`（未闭环，不计入率，单列提示）。
+> 聚合：`node .agents/scripts/agg-delegations.cjs` → 输出各月指标 + 扩容门判定 + 可粘贴快照行，粘贴进 §月度聚合快照（每月一行）。聚合时顺路按「三类清理清单」巡检 AGENTS.md：代码/配置已可推导的删；只针对一次需求的细节移 wiki 或删；已被脚本/hook/测试自动保证的只留入口。
+> 口径说明：合并冲突率不适用（单人串行 + 每阶段确认）；人工复核负担以「复核类委派的返工行」近似（见结果列 + 备注）。
+> 调整某角色的模型指派前，先从 `workflow/incidents/` 取 3 个已定性 bug 丢给候选模型做回归对比，再拍板。
+
+## 委派结果
+
+| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 |
+|------|----------------|------------|------|------|
+
+## 自做任务结果
+
+| 日期 | 任务一句话 | 结果 | 备注 |
+|------|------------|------|------|
+
+## 月度聚合快照
+
+（`node .agents/scripts/agg-delegations.cjs` 输出的可粘贴快照行落这里，每月一行）
+
+## 并发扩容门槛
+
+连续两个月一次完成率 ≥ 90%、月度返工次数为 0 且无主兜底信号，才考虑扩大并发委派；任一不达标维持单并发。门槛判定由聚合脚本输出，两处同步修改。

package/templates/workflow/incidents/_TEMPLATE.md

@@ -0,0 +1,42 @@
+---
+状态: open
+级别: L1
+发现: YYYY-MM-DD
+模块: <词表之一，见 .agents/workflow-modules.txt>
+---
+# INCIDENT — <日期 主题>
+<!-- 复制为 YYYY-MM-DD-<主题>.md；线上或实测发现的功能缺陷都记录，历史 BUG 可回填 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈open/fixed/closed（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；闭环引擎启用前的回填件加一行 `流程: legacy`（豁免级别/配对检查）；正文不再写状态/级别/发现行 -->
+
+## 时间线
+- <发现 → 定位 → 止血 → 恢复，带时刻>
+
+## 影响面
+- <页面 / 接口 / 数据范围>
+
+## 根因
+<一句话；深层原因另起一行>
+
+## 为什么之前没拦住
+<门禁 / 测试 / 规范各查一遍：哪一层本可以拦住>
+
+## 复盘三件套（缺一不可）
+
+> 目的：让事故真正回到 Plan，不让「防复发」承诺停留在文档里。模块已逐步上线，事故可能来自 dev / staging / prod 任一环境。
+
+1. 结构性修复
+   - 修复 commit：<SHA + 改动文件清单>
+   - 影响环境：dev / staging / prod（已上线模块若波及 prod，需附影响用户数 / 持续时长 / 是否回滚）
+   - 是否需要新 intent：
+     - 是 → ../intents/YYYY-MM-DD-<主题>.md（根因属「门禁缺位 / 规范未落地 / 系统性问题」时强制立，即使结构性修复已完成）
+     - 否 → 理由：<根因属实现 bug、单点修复已完成，且已有规范条目覆盖>
+
+2. 防复发验证（必须落到自动化用例或回归清单条目，禁止只写「已人工验证」）
+   - 自动化用例：项目测试套件 <文件>（<用例名 / 数量>）
+   - 或 test 步骤：.agents/commands/test.md + <具体操作>
+   - 或回归清单条目：workflow/regression-checklist.md（防复发验证节追加一行）
+
+3. 规范条目（必须有可追溯的落点）
+   - 落点（多选）：AGENTS.md <章节> / .agents/hooks/<脚本> / .agents/skills/<skill> / .agents/commands/<cmd> / 回归清单 §<章节>
+   - 引用：commit <SHA> / 文件:<路径>#L<行>
+   - 若无新增条目，理由：<已有条目覆盖，说明条目位置>

package/templates/workflow/intents/_TEMPLATE.md

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

package/templates/workflow/papercuts.md

@@ -0,0 +1,7 @@
+# 命令/技能 Papercut 留痕
+
+> `.agents/commands/`、`.agents/roles/` 或已装技能在真实任务中卡住、误导、缺步骤时记一行，**不当场顺手改**。
+> 同一文件命中第 2 次或用户点名时，升级为 docs 修复 commit。
+
+| 日期 | 位置 | 症状 | 拟修 |
+|------|------|------|------|

package/templates/workflow/plans/_TEMPLATE.md

@@ -0,0 +1,38 @@
+---
+状态: draft
+级别: L1
+模块: <词表之一，见 .agents/workflow-modules.txt>
+---
+# PLAN — <与入口文档同名主题>
+<!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2/L3 必须先有 ../specs/ 同名 spec 确认通过；AI 起草、用户对话内确认后开工 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；正文不再写状态/级别行 -->
+<!-- L1 极简形态（2026-09-13 瘦身，L1 默认）：单/少文件微改动只填「改动面」+「验证方式」两节——改动面逐条列改哪个文件做什么（判据细节直接写进条目），验证一行静态门 + 按需 UI 实测；任务拆解/执行顺序仅 L1 多文件多步骤时保留 -->
+
+对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）
+对应 spec：../specs/YYYY-MM-DD-<主题>.md（L1 可省略）
+
+## 改动面（L1 极简形态主节；L2/L3 可作任务拆解的汇总或删本节）
+- <文件/组件>：<做什么；判据细节直接写进条目，如「L771 message.success 改『更新成功』」>
+
+## 任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）
+1. <任务>
+   - 判据：<怎样算完成；尽量对应一个测试或可复现操作>
+   - 风险：低 / 中 / 高（<原因>）
+2. <任务>
+   - 判据：…
+   - 风险：…
+
+## 执行顺序（L2/L3 必填；L1 单文件微改动删本节）
+<1 → 2 → 3；标注依赖关系>
+
+## 验证方式
+- 静态门：`项目构建命令`（+ `项目测试命令`，测试项目就绪后）
+- 前端：cd frontend && npm run build（vue-tsc）
+- UI：.agents/commands/test.md（涉及页面改动必走，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 草稿全文过目 + 改动清单确认（`build.md` 两道门，逐次，不合并）

package/templates/workflow/regression-checklist.md

@@ -0,0 +1,22 @@
+# 回归清单（活文档）
+
+> 用途：deploy 清单「回归必过」与 incidents 复盘「防复发验证」的统一落点。
+> 本清单是**活文档**：随模块上线补充、随 incident 追加、随功能演进修订；代码演进后以本清单与实际行为为准。
+
+## 维护规则
+
+1. **deploy 前**：过本清单中「涉及模块」的全部条目 + 跑自动化测试（项目防复发用例）
+2. **incident 后**：防复发条目追加到「防复发验证」节，不留在 incident 文档里；能自动化的落测试用例
+3. **模块上线/走查后**：为该模块补关键路径条目
+4. 条目过时（功能下线/行为变更）时删除或改写，不保留失效条目
+5. **新增防复发条目落点优先级**：自动化用例 > 脚本化断言 > 人工步骤（仅剩视觉/交互断言无法脚本化时）
+
+## 回归必过
+
+| 模块 | 条目 | 依据 |
+|------|------|------|
+
+## 防复发验证
+
+| incident | 条目 | 落点 |
+|----------|------|------|

package/templates/workflow/specs/_TEMPLATE.md

@@ -0,0 +1,41 @@
+---
+状态: draft
+级别: L1
+模块: <词表之一，见 .agents/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 强制校验） -->
+
+对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）
+
+## 功能行为
+<讲清功能怎么工作；分小节列用户 / 系统行为，必要时附状态机 / 时序图说明>
+
+## 数据流
+<数据从哪里来 → 经过哪些处理 → 落到哪里；含字段映射、接口契约、上下游依赖>
+
+## 系统改动清单
+- 后端：模块 / 文件 / 接口契约
+- 数据库：无 / <表名 + 字段 + 迁移 SQL 路径>
+- 前端：路由 / 组件 / store / api
+
+## 约束遵守映射（对照 AGENTS.md 触达红线）
+| 红线（按本项目 AGENTS.md 实际红线逐行填，没有的行删除） | 本 spec 如何满足 |
+|------|------------------|
+| <示例：分层依赖约束 / 编码权威归属 / 数据迁移方式> | <通过 XXX，不引入 YYY；是否触及（触及即 L2 定级依据）> |
+| <示例：schema / 迁移路径约束> | <涉及路径与处理方式> |
+| <示例：前端或客户端约定（如有）> | <本 spec 涉及哪些约定> |
+
+## 风险评估
+- <风险点 1> ｜ 应对：<测试 / hook / 评审>
+- <风险点 2> ｜ 应对：…
+
+## 确认与复核
+> 个人工作流：确认 = 用户在对话内一句话通过；无第二审批人，追溯靠 git（commit 记录确认时点）。
+> 确认结果 / 确认时间写在文件头 frontmatter（L3 由 check-loop 强制校验）；本节只留叙述性复核记录。
+
+- 独立复核：<L3 强制：另开新会话由 AI 复核本 spec，记录复核会话与结论；L1 / L2 无则删除本行>
+- 复核结论：<无则删除本行>
+- 返修意见：<无则删除本行>
+- 确认通过后，方可起草 ../plans/YYYY-MM-DD-<主题>.md