agentic-flow-kit 1.8.7 → 2.0.0

package/templates/git/.githooks/pre-push

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发；全 node 化——
+// git 仍以自带 sh 启动本文件（钩子机制要求），但她bang 即 node，PATH 无 sh 不影响任何逻辑。
+// 写法为 CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ≥22.7 的 ESM 语法探测）
+// 跑 node .agents/scripts/check-loop.mjs：默认只扫 hard 5 段（配对 / 回归证据 / 证据真相 / 确认指纹 / 收敛对账）
+// 构建门（自 pre-commit 后移）：另跑 commit-check.cjs --range <old> <new> 按推送范围条件构建
+// （常规提交时刻只做敏感扫描——提交内环提速；构建执法集中到推送与关单）。
+// （去 sh 化收尾：兼容 shim check-loop.sh 已删，钩子直调 .mjs）
+//   - 硬阻断（exit 1）= check-loop hard 5 段判非绿 → push 立即阻断（原清单中的「发版未收口」§17 已于 2026-10-21 退役删码，不在扫描面）
+//   - hygiene 段已于 2026-10-28 全部退役（引擎减重第一刀）——本钩子只扫 hard 5 段。
+// stdin 有行时，hard 扫描按推送范围 old..new（C3，2026-10-28；新分支远端全零回退 --rev 扫尖端树）。没有行时（手跑钩子）仍无参数扫工作区。
+//
+// experiment/* 泳道（hybrid-governance-explore-hardening）：**目标分支**为 experiment/* 时，
+//   闭环扫描降级 advisory（报告不阻断）——快速 PoC 推送不因闭环断档被拦。
+// （原转正加固门——push 目标 main 时 --hardening 扫 exploring 收口——已退役，
+//   见 .agents/config/mechanism-registry.md；main 推送回归普通全量扫描。）
+//
+// 机器门：本地钩子（本地机器门）+ 远端 CI 业务面兜底（azure-pipelines.yml；
+//   trigger main + develop：main 直推跑 verify --full（全量 20 门，含密钥门），develop 直推跑 verify --mid（业务面 + 后端单测）——三档化 2026-10-29；治理门全在本地——口径单源 runtime-env §6.5）。
+//   （PR 面板评审台账门已于 2026-11-09 退役为手动工具——自动门拆除，编排见 .agents/commands/pr-review.md。）
+// 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-push: 无法定位仓库根（git rev-parse --show-toplevel 失败）——推送已阻止');
+  process.exit(1);
+}
+process.chdir(top.stdout.trim());
+
+const SCRIPT = '.agents/scripts/check-loop.mjs';
+// 闭环脚本随仓走——缺失 = checkout 残缺/误删，fail-closed 阻断（prepush-script-missing-failclosed）
+if (!fs.existsSync(SCRIPT)) {
+  console.error(`pre-push: 未找到 ${SCRIPT}——闭环扫描无法执行，推送已阻止（脚本随仓走；git checkout -- ${SCRIPT} 恢复后重试）`);
+  process.exit(1);
+}
+
+// 构建门（自 pre-commit 后移）：非 experiment 目标推送按 old..new 范围跑条件构建
+// （commit-check.cjs --range——匹配逻辑单源：触及 .cs/.sln/.csproj → dotnet build、触及 frontend/
+// → npm run build；远端全零 sha 的新分支首推 = 全量构建语义）。experiment/* 目标降级 advisory。
+// 手动运行（无 stdin 推送行）无范围事实，构建门跳过。脚本缺失 fail-closed。
+const BUILD_CHECK = '.agents/hooks/commit-check.cjs';
+if (!fs.existsSync(BUILD_CHECK)) {
+  console.error(`pre-push: 未找到 ${BUILD_CHECK}——构建门无法执行，推送已阻止（脚本随仓走；git checkout -- ${BUILD_CHECK} 恢复后重试）`);
+  process.exit(1);
+}
+
+// 推送级改动面门（2026-11-09 建）：非 experiment 目标推送按 old..new 范围跑 check-scope-range——
+// 范围内新增/修改的 plan 声明文件并集 vs 范围 diff，只判越界方向（改了未声明）；无 plan 变更 skip。
+// 补提交时刻 check-confirm-order 的盲面：确认门只看单条提交，多提交合推夹带 plan 外文件由此拦截。
+// 脚本缺失 fail-closed（与 BUILD_CHECK 同口径）。
+const SCOPE_RANGE = '.agents/scripts/check-scope-range.mjs';
+if (!fs.existsSync(SCOPE_RANGE)) {
+  console.error(`pre-push: 未找到 ${SCOPE_RANGE}——推送级改动面门无法执行，推送已阻止（脚本随仓走；git checkout -- ${SCOPE_RANGE} 恢复后重试）`);
+  process.exit(1);
+}
+const rangeArgsOf = (remoteSha, localSha) => ['--range', remoteSha && !/^0+$/.test(remoteSha) ? remoteSha : '0'.repeat(40), localSha];
+
+const runLoop = (args = []) => spawnSync(process.execPath, [SCRIPT, ...args], { stdio: 'inherit' });
+
+// hard 5 段最小回归条件段已于 2026-10-31 摘除（c16eec41）、2026-11-06 重新摘除：其套件
+// `.agents/scripts/check-loop-hard-sections.test.mjs` 从未入库（被 .gitignore 的 `.agents/**/*.test.mjs`
+// 排除），引用与「文件随仓走」自相矛盾——钩子对任何推送都落在「文件缺失」分支。c16eec41 已删净本段，
+// 但 60da7324 合并时本文件取了含死段的那一侧（loud-skip 版），摘除被回滚。本次按 commit 原意重新摘除，
+// 并同步修 runtime-env.md §5 与 papercuts 台账失实行。hard 段回归改由入库探针
+// `node .agents/scripts/check-loop-rev-semantics.mjs` 手动承担（engine-tests 全量已于 2026-10-28 退役）。
+
+
+// 后端集成测试档（2026-10-29 backend-unit-tier，owner 拍板「关单只跑单测」）：本地关单 backend-test
+// 降单测档（--unit-only ~5.6s），集成测试（单库串行，Deve_CSS_SuHao；2026-10-30 分区机制退役）移到本钩子——
+// 推送范围触及后端面时按影响面选测（2026-11），仅共享层/工程文件/未登记映射回退全量。
+// 面判据单源 = verify-scope.mjs PRODUCT_FACES.backend.match；2026-11 起本钩子收紧为路径面：
+// backend/|tests/|scripts/verify/backend/ + 后端侧工程文件 + 后端/测试/脚本面 SQL。
+// wiki schema 变更/数据修复 SQL 触发；其它数据维护 SQL、frontend/ 与仓库外脚本不触发集成档。
+// 新分支首推/范围判不出 → 保守跑。experiment/* 泳道不跑。
+// 所有范围 git diff 统一带 -c core.quotepath=off --no-renames：中文路径不转义，重命名不丢旧路径。
+const BACKEND_TEST = 'scripts/verify/backend/run-backend-tests.mjs';
+const BACKEND_FACE_RE = /^(backend|tests|scripts\/verify\/backend)\//i;
+const BACKEND_BUILD_FILE_RE = /\.(sln|csproj|props|targets)$/i;
+const BACKEND_SQL_RE = /\.sql$/i;
+const SCHEMA_CHANGE_SQL_RE = /^wiki\/数据维护\/schema变更\//i;
+const DATA_REPAIR_SQL_RE = /^wiki\/数据维护\/数据修复\//i;
+const isBackendFaceFile = (file) => {
+  const p = (file || '').trim();
+  if (!p) return false;
+  if (BACKEND_FACE_RE.test(p)) return true;
+  if (BACKEND_BUILD_FILE_RE.test(p) && !p.startsWith('frontend/') && !p.startsWith('node_modules/')) return true;
+  if (BACKEND_SQL_RE.test(p) && (/^(backend|tests|scripts)\//i.test(p) || SCHEMA_CHANGE_SQL_RE.test(p) || DATA_REPAIR_SQL_RE.test(p))) return true;
+  return false;
+};
+const touchedBackend = (oldSha, newSha) => {
+  if (/^0+$/.test(oldSha)) return true;
+  const d = spawnSync('git', ['-c', 'core.quotepath=off', 'diff', '--name-only', '--no-renames', `${oldSha}..${newSha}`], { encoding: 'utf8' });
+  if (d.status !== 0) return true; // 范围判不出 → 保守跑
+  return (d.stdout || '').split(/\r?\n/).some(isBackendFaceFile);
+};
+
+// 接线一致性（2026-10-29 P0）：宿主接线宣称 ↔ 实态对账——引擎测试面退役后接线漂移的唯一机检
+// （实证案例见 check-hook-wiring.mjs 头注：registry 记坐实/实态 disabled、判据脚本无挂载点）。
+// 触发面：推送范围触及宿主壳 / .agents/hooks/ / registry；新分支/范围判不出 → 保守跑。
+const WIRING_CHECK = '.agents/scripts/check-hook-wiring.mjs';
+const WIRING_FACE_RE = /^(?:\.zcode|\.trae|\.codebuddy|\.opencode|\.claude|\.qwen|\.pi|\.cline|\.commandcode|\.qoder)\//;
+const touchedWiring = (oldSha, newSha) => {
+  if (!fs.existsSync(WIRING_CHECK)) {
+    console.error(`pre-push: 未找到 ${WIRING_CHECK}——接线对账脚本随仓走，推送已阻止`);
+    return true;
+  }
+  if (/^0+$/.test(oldSha)) return true;
+  const d = spawnSync('git', ['-c', 'core.quotepath=off', 'diff', '--name-only', '--no-renames', `${oldSha}..${newSha}`], { encoding: 'utf8' });
+  if (d.status !== 0) return true; // 范围判不出 → 保守跑
+  return (d.stdout || '').split(/\r?\n/).some((f) => {
+    const t = f.trim();
+    return WIRING_FACE_RE.test(t) || t.startsWith('.agents/hooks/') || t === '.agents/config/mechanism-registry.md';
+  });
+};
+
+// stdin（git 以管道喂入待推引用行；手跑钩子无管道 → 空输入走工作区扫描路径）
+let stdinText = '';
+try { stdinText = fs.readFileSync(0, 'utf8'); } catch { /* 无管道输入 */ }
+
+let saw = 0;
+let rc = 0;
+for (const line of stdinText.split(/\r?\n/)) {
+  if (!line.trim()) continue;
+  const parts = line.trim().split(/\s+/);
+  if (parts.length < 4) continue;
+  const [localRef, localSha, remoteRef, remoteSha] = parts;
+  saw = 1;
+  if (/^0+$/.test(localSha)) continue; // 删除推送不扫
+  // 按目标分支分派（判定键 = remote_ref，v09-review-defects）：
+  //   experiment/* → advisory（报告不阻断）；其余（含 main）→ 硬门扫描（卫生段不在本钩子）
+  // P1 修复（2026-11-06）：原 remoteRef.includes('experiment/') 是任意位置子串——
+  // refs/heads/foo/experiment/x 或同名 tag 也会被降级 advisory，等于绕开硬门。
+  // 收紧为精确匹配 refs/heads/experiment/ 分支命名空间前缀。
+  if (/^refs\/heads\/experiment\//.test(remoteRef)) {
+    console.error(`pre-push: experiment/* 目标分支（${remoteRef}）——闭环扫描降级 advisory，不阻断`);
+    const adv = spawnSync(process.execPath, [SCRIPT, '--rev', localSha]);
+    const advOut = `${adv.stdout || ''}${adv.stderr || ''}`;
+    if (adv.status !== 0) console.error(`pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送\n${advOut}`);
+    const advB = spawnSync(process.execPath, [BUILD_CHECK, ...rangeArgsOf(remoteSha, localSha)], { stdio: 'inherit' });
+    if (advB.status !== 0) console.error('pre-push: （advisory）构建门未过已在上方列出——experiment 泳道不阻断推送');
+  } else {
+    // C3（2026-10-28）：hard 扫描改扫推送范围 old..new——中间提交不再只看尖端；新分支（远端全零）回退 --rev
+    const r = /^0+$/.test(remoteSha) ? runLoop(['--rev', localSha]) : runLoop(['--range', remoteSha, localSha]);
+    if (r.status !== 0 && rc === 0) rc = r.status === null ? 1 : r.status;
+    const rb = spawnSync(process.execPath, [BUILD_CHECK, ...rangeArgsOf(remoteSha, localSha)], { stdio: 'inherit' });
+    if (rb.status !== 0 && rc === 0) rc = rb.status === null ? 1 : rb.status;
+    // 推送级改动面门：范围含 plan 变更才对账（脚本内自判 skip）；old 全零新分支首推脚本内 skip
+    const rs = spawnSync(process.execPath, [SCOPE_RANGE, remoteSha, localSha, '--strict'], { stdio: 'inherit' });
+    if (rs.status !== 0 && rc === 0) rc = rs.status === null ? 1 : rs.status;
+    // 后端集成测试档：关单单测化后集成的执法点（范围触后端面才跑；CI 重档另有全量兜底）
+    //   2026-11 影响面选测：单测先跑 → 按推送净 diff 选集成子集 → 共享层/工程文件/未登记
+    //   测试类/映射缺失自动回退全量（fail-safe）。选测口径单源 .agents/config/test-impact-map.json。
+    //
+    // 登记式跳过（PREPUSH_SKIP_INTEGRATION，2026-10-29 建）已于 2026-11-08 档 3 清退：
+    //   本地集成档默认交 CI 后该开关无可跳之物（近 30 日零触发）；已知红走 incident/papercut 台账。
+    if (touchedBackend(remoteSha, localSha)) {
+        // 2026-11-08 减重（owner 指示「本地别每次都跑集成」）：集成档默认不在本地跑——
+        // 单次推送实测 ~80s（905 条，且 test-impact-map 缺登记时恒回退全量），而同一套件在
+        // CI（develop/main 档 verify --mid/--full）恒跑。本地只跑单测档：--unit-range 按推送
+        // range 裁单测集（2026-11-08 接线 3-U4；映射缺失/后端生产面/受影响集为空 → 回落全量
+        // 单测 fail-open，一行提示；只有直接触及单测测试文件时才只跑被触及的类）。
+        // 恢复本地集成执法：PREPUSH_RUN_INTEGRATION=1 git push。
+        const runIntegration = (process.env.PREPUSH_RUN_INTEGRATION || '').trim() === '1';
+        if (runIntegration) {
+          console.error('pre-push: 推送范围触及后端面——单测 + 影响面选测（PREPUSH_RUN_INTEGRATION=1）');
+          const oldSha = /^0+$/.test(remoteSha) ? '0'.repeat(40) : remoteSha;
+          const rt2 = spawnSync(process.execPath, [BACKEND_TEST, '--select-range', oldSha, localSha], { stdio: 'inherit' });
+          if (rt2.status !== 0 && rc === 0) rc = rt2.status === null ? 1 : rt2.status;
+        } else {
+          console.error('pre-push: 推送范围触及后端面——单测档按影响面选测（集成档交 CI：develop/main 档 verify --mid/--full）');
+          console.error('pre-push: ⚠️ 本地未跑集成测试，这不是集成绿凭证；需要本地复现时加 PREPUSH_RUN_INTEGRATION=1。');
+          const oldSha = /^0+$/.test(remoteSha) ? '0'.repeat(40) : remoteSha;
+          const rt2 = spawnSync(process.execPath, [BACKEND_TEST, '--unit-range', oldSha, localSha], { stdio: 'inherit' });
+          if (rt2.status !== 0 && rc === 0) rc = rt2.status === null ? 1 : rt2.status;
+        }
+    }
+    // 接线一致性：触接线面才跑（实测 <1s）
+    if (touchedWiring(remoteSha, localSha)) {
+      const rw = spawnSync(process.execPath, [WIRING_CHECK], { stdio: 'inherit' });
+      if (rw.status !== 0 && rc === 0) rc = rw.status === null ? 1 : rw.status;
+    }
+  }
+}
+
+if (saw === 0) {
+  const r = runLoop();
+  if (r.status !== 0) rc = r.status === null ? 1 : r.status;
+  console.error('pre-push: 手动运行无推送范围——构建门跳过（真实推送时按 old..new 范围执法）');
+}
+
+if (rc !== 0) {
+  console.error('pre-push: 闭环骨架断档（hard-block）未通过，push 已阻断。修 workflow 文档后重推——不要用 --no-verify 绕过。本地钩子已阻断本次推送；远端另有 CI（main verify --full 全量 20 门）兜底。');
+  process.exit(rc);
+}
+
+// 治理面 advisory 已于 2026-10-28 全部退出 pre-push（owner 决策）：PR 体积预算、papercut 欠账提醒、
+// 回路日检（agg-judgments 月度分片 / retire-watch / papercut-report）不再随推送运行。
+// 上述脚本保留为手动工具（需要时直接 node 跑），本钩子只做 hard 扫描 + 条件构建。
+process.exit(0);

package/templates/git/.gitignore.engine

@@ -0,0 +1,11 @@
+# 引擎运行态（各机各自产生，不共享）
+.agents/cache/
+.agents/tmp/
+.agents/tools/
+.agents/verifications.jsonl
+.agents/judgments.jsonl
+.agents/notes/runtime-env.local.md
+.agents/config/model-roles.local.json
+
+# 本机宿主目录（默认不入库；--track-hosts 可关闭）
+{{hostIgnores}}

package/templates/hosts/claude/CLAUDE.md

@@ -0,0 +1,55 @@
+<!-- 本文件为根 AGENTS.md 在 Claude Code 宿主的本机镜像（2026-11-11 移植）。
+     权威源仍为 AGENTS.md；AGENTS.md 更新后须同步本文件。本文件不入库（.gitignore）。 -->
+
+# Repository Guidelines
+
+船厂物资管理系统。ASP.NET Core 6 后端（Clean Architecture 双模块）+ Vue 3 + SQL Server。
+
+## 1. 运行时联通 (Runtime Connectivity)
+前端 dev 5203 连 API `http://localhost:8932`；API 须监听 8932 才联通。端口/工具缺陷/可执行文件解析机理等环境事实见 `.agents/notes/runtime-env.md` §6；各机绝对路径与版本自登记 `.agents/notes/runtime-env.local.md`。
+
+## 2. 本地 Clone 必做 (Local Setup)
+> 漏配则门禁静默失效，详见 `.agents/notes/runtime-env.md` §7。
+- `git config core.hooksPath .githooks` 挂仓库自带钩子。
+- `git config merge.ours.driver true` 启用 `appsettings.json` 的 `merge=ours` 策略。
+- `git config merge.jsonl-union.driver "node .agents/scripts/git-merge-jsonl.mjs %O %A %B"` 启用 `.agents/*.jsonl` 并集合并策略。
+- **禁令**：commit / merge / push 三处一律禁 `--no-verify`。
+- **自检**：`node .agents/scripts/check-local-gates.mjs --fix`
+
+## 3. 全局红线 (Universal Laws)
+- **安全/隐私**：不提交密钥、令牌、`.env` 或真实用户数据；发现敏感信息立即停止扩散。
+- **不可逆操作**：默认不执行生产部署、远程推送、数据删除等操作 → 须用户明确要求且不得绕过门禁。
+- **最小改动**：优先做满足需求的最小改动，禁止顺手重构无关代码、修改格式或修复无关 Lint 警告。
+- **单源纪律**：路径 / 版本 / 缺陷等环境事实只登记于 `.agents/notes/runtime-env.md` §6，别处禁止复制原文。
+- **上下文纪律**：批量取数、长日志、大 diff、全仓盘点交子代理，主线只收结论摘要与 `file:line`；子代理回报写结论与证据路径，禁把原始输出整段搬回主线。
+- **提交规范**：Conventional Commits 中文，类型限 `feat/fix/docs/style/refactor/perf/chore`。
+
+## 4. 阶段路由表 (Workflow Routing)
+按任务类型跳转对应指令文件：
+
+| 任务类型 | 指令文件 | 核心职责 |
+|---|---|---|
+| **L0 极简道** | `.agents/commands/new-task.md` | 全机器可判的极小改动，与 L1 同走快速道：改码 → `verify --face`/`--scope` → 单笔 commit；判据与仲裁见 new-task.md §L0 极简道 |
+| **L1 快速道** | `.agents/commands/new-task.md` | 定级、实现、`verify --scope`、单笔关单（仅独立关单场景开技能）。不打开 `stages.md` |
+| **新需求 / 功能** | `.agents/commands/new-task.md` | L1 走上一行快速道；L2/L3 才进 `stages.md` |
+| **L2/L3 阶段流（意图 → 设计 → 实现 → 验证关单）** | `.agents/commands/stages.md` | 四章 Plan→Design→Build→Test：立 intent → 起 spec → 起 plan + 实现 → 静态门 → UI 实测 → 独立复核 → 关单。L1 不进 |
+| **修复 / 事故** | `.agents/commands/maintain.md` | L1 非事故只做 §1 立档后回快速道。线上事故与 L2/L3 读全文 |
+| **上线 / 发布** | `.agents/commands/deploy.md` | 静态门 → 回归检查（含 DB 验证）→ 授权 → PR 审查合并 |
+| **合入评审** | `.agents/commands/review.md` | P0/P1/P2 分级评审 → 结论定性 |
+| **自动化驱动** | `.agents/commands/pipeline-run.md` | 实验位保留待用：状态机尚未验证、零 run 记录，启用前须补状态机测试——口径以 pipeline-run.md 自述为准；与手动阶段路由二选一，禁混用 |
+| **无人值守 / 过夜** | `.agents/skills/autonomous-run/SKILL.md` | 长跑合同：逐单元签收 + 停机条件；门禁与确认门不豁免，可挂 pipeline-run 驱动（实验位待用） |
+| **性能 / 视觉对齐** | `.agents/skills/perf/SKILL.md` · `.agents/skills/visual-parity/SKILL.md` | 先基线后单变量；像素对齐只改样式，差异表清零才宣称一致 |
+
+> **纠偏短名**：任务中途报短名即可，索引 `.agents/config/principles.md`。
+
+> **引擎面豁免**：改 AI-Native 治理引擎自身，**豁免工作流三件套**——不生成 intents/specs/plans、不走确认门，Conventional Commits 直接变更。引擎面 = `.agents/` 全部、`.zcode/`、`.githooks/`、`azure-pipelines.yml`、workflow/ 模板与台账、根 `package.json`、宿主适配目录 `.opencode/`、`.trae/`、`.codebuddy/`、`.qwen/`、`.pi/`、`.cline/`、`.commandcode/`、`.claude/`；其中 `.pi/`、`.cline/`、`.commandcode/`、`.claude/` 等本机私有目录不入库、不随 clone 传播，其门禁接线完整性由 `check-local-gates.mjs` advisory 对账（机理 `.agents/notes/runtime-env.md` §6.4）。**wiki 豁免**：调整 `wiki/` 知识文档内容（含 INDEX 与看板）同享上述豁免，`docs(wiki)` 直接变更。**边界**：git 钩子与静态门照常执行；删除 wiki 文件仍须用户单独指令；数据维护 SQL 的**执行**不豁免，仍按数据维护台账与 DB 验证口径走；触及 `backend/`、`frontend/`、数据维护 SQL 等**业务面**不豁免，按下表级别走闭环；混合改动只对业务部分立档。
+
+## 5. 目录级规则 (Directory-level Rules)
+**禁止回填本文档**。具体实现细节请查阅对应目录的 `AGENTS.md`：
+- **后端**: `backend/AGENTS.md` (.NET 开发规范 / 数据完整性 / API 契约 / 数据库操作)
+- **前端**: `frontend/AGENTS.md` (前端开发规范 / 类型检查 / 契约与门禁 / UI 实测门)
+- **成对文档同步**：`wiki/用户功能/物资系统功能验证手册-一期.{html,md}` 与 `wiki/用户功能/全流程与数据主线.{html,md}` 必须成对维护；修改任一份须同步另一份，并同步更新 `wiki/INDEX.md` 与 `wiki/知识沉淀总览.html`。
+
+## 6. 项目适配区 (Project Adaptations)
+- **构建/测试/类型检查**: 命令清单单源 `.agents/hooks/commit-check.config.json`。
+- **冒烟探活**: 脚本路径与 6 端点判定事实见 `.agents/notes/runtime-env.md` §6.1。

package/templates/hosts/claude/agents/implementer.md

@@ -0,0 +1,7 @@
+---
+name: implementer
+description: Implements an approved, tightly scoped code change or test when the task includes owned files and executable acceptance criteria
+model: inherit
+---
+
+公共角色契约：`.agents/roles/implementer.md`。本文件只保留宿主 frontmatter。

package/templates/hosts/claude/agents/independent-reviewer.md

@@ -0,0 +1,8 @@
+---
+name: independent-reviewer
+description: Independently reviews a fixed spec, plan, or code diff for correctness and project-rule violations without modifying files
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+公共角色契约：`.agents/roles/independent-reviewer.md`。本文件只保留宿主 frontmatter。只读复核，禁止修改仓库文件。

package/templates/hosts/claude/agents/pr-adjudicator.md

@@ -0,0 +1,8 @@
+---
+name: pr-adjudicator
+description: PR 面板评审的只读裁决者；处理 escalated 候选并返回裁决
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+公共角色契约：`.agents/roles/pr-adjudicator.md`。本文件只保留宿主 frontmatter。只读裁决，禁止修改仓库文件。

package/templates/hosts/claude/agents/pr-finder.md

@@ -0,0 +1,8 @@
+---
+name: pr-finder
+description: PR 面板评审的只读 finder；按镜头独立找 bug，返回候选 JSON
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+公共角色契约：`.agents/roles/pr-finder.md`。本文件只保留宿主 frontmatter。只读找 bug，禁止修改仓库文件。

package/templates/hosts/claude/agents/pr-verifier.md

@@ -0,0 +1,8 @@
+---
+name: pr-verifier
+description: PR 面板评审的只读 verifier；独立验证单条候选并返回票 JSON
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+公共角色契约：`.agents/roles/pr-verifier.md`。本文件只保留宿主 frontmatter。只读验证，禁止修改仓库文件。

package/templates/hosts/claude/agents/ui-verifier.md

@@ -0,0 +1,8 @@
+---
+name: ui-verifier
+description: Runs browser-based verification for an implemented UI change and returns reproducible evidence without editing repository files
+tools: Read, Grep, Glob, Bash, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__new_page, mcp__chrome-devtools__list_pages, mcp__chrome-devtools__select_page, mcp__chrome-devtools__close_page, mcp__chrome-devtools__take_snapshot, mcp__chrome-devtools__take_screenshot, mcp__chrome-devtools__click, mcp__chrome-devtools__fill, mcp__chrome-devtools__fill_form, mcp__chrome-devtools__type_text, mcp__chrome-devtools__press_key, mcp__chrome-devtools__hover, mcp__chrome-devtools__drag, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__wait_for, mcp__chrome-devtools__resize_page, mcp__chrome-devtools__emulate, mcp__chrome-devtools__list_console_messages, mcp__chrome-devtools__get_console_message, mcp__chrome-devtools__list_network_requests, mcp__chrome-devtools__get_network_request, mcp__chrome-devtools__handle_dialog, mcp__chrome-devtools__upload_file, mcp__chrome-devtools__get_css_styles, mcp__chrome-devtools__performance_start_trace, mcp__chrome-devtools__performance_stop_trace, mcp__chrome-devtools__performance_analyze_insight, mcp__chrome-devtools__take_heapsnapshot, mcp__chrome-devtools__lighthouse_audit, mcp__chrome-devtools__screencast_start, mcp__chrome-devtools__screencast_stop
+model: inherit
+---
+
+公共角色契约：`.agents/roles/ui-verifier.md`。本文件只保留宿主 frontmatter。只读实测，禁止修改仓库文件。

package/templates/hosts/claude/agents/wiki-compiler.md

@@ -0,0 +1,8 @@
+---
+name: wiki-compiler
+description: Translates a code commit into strict JSON describing what business capability the system gained, written for non-coding readers (product/customer service); read-only analysis, never edits files
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+公共角色契约：`.agents/roles/wiki-compiler.md`。本文件只保留宿主 frontmatter。只读翻译，禁止修改仓库文件。

package/templates/hosts/claude/commands/wf-deploy.md

@@ -0,0 +1,10 @@
+---
+description: Deploy 阶段：合入清单（静态门 + 配对检查 + 回归 + DB + 授权 + PR 审查合并）
+argument-hint: [发布范围]
+---
+
+权威命令：`.agents/commands/deploy.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/commands/wf-maintain.md

@@ -0,0 +1,10 @@
+---
+description: Maintain 阶段：立 incident + 复盘三件套（修复 / 防复发 / 规范条目）
+argument-hint: [事故或问题描述]
+---
+
+权威命令：`.agents/commands/maintain.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/commands/wf-new-task.md

@@ -0,0 +1,10 @@
+---
+description: New Task 闭环总入口：先定级再路由（L0/L1 快速道；L2/L3 转 wf-stages）
+argument-hint: [任务描述]
+---
+
+权威命令：`.agents/commands/new-task.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/commands/wf-pipeline-run.md

@@ -0,0 +1,10 @@
+---
+description: pipeline-run 自动化驱动入口——单命令驱动六阶段闭环（工单协议 + 机器门 + 原话代录）；与手动阶段路由二选一，禁混用
+argument-hint: [工单或任务描述]
+---
+
+权威命令：`.agents/commands/pipeline-run.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/commands/wf-pr-review.md

@@ -0,0 +1,10 @@
+---
+description: PR 面板评审——多子代理找 bug + 独立投票 + 台账
+argument-hint: [PR 编号或范围]
+---
+
+权威命令：`.agents/commands/pr-review.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/commands/wf-review.md

@@ -0,0 +1,10 @@
+---
+description: 代码评审标准（按风险分级：机器兜底 + AI 自查出清单，用户决策定性和合入）
+argument-hint: [评审范围]
+---
+
+权威命令：`.agents/commands/review.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/commands/wf-stages.md

@@ -0,0 +1,10 @@
+---
+description: L2/L3 阶段流（四并一）：Plan 立 intent → Design 起 spec → Build 起 plan + 实现代码 → Test 静态门 + UI 实测 + 复核 + 关单；L1 走 wf-new-task
+argument-hint: [阶段或任务描述]
+---
+
+权威命令：`.agents/commands/stages.md`
+
+本文件是指针壳。执行时读取权威源，不在此复制正文。
+
+用户随命令附带的参数：$ARGUMENTS

package/templates/hosts/claude/settings.json

@@ -0,0 +1,57 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dotnet build:*)",
+      "Bash(dotnet run:*)",
+      "Bash(npm run:*)",
+      "Bash(npm install:*)",
+      "Bash(npm ci:*)",
+      "Bash(node:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git log:*)",
+      "Bash(git push:*)",
+      "Bash(chrome:*)"
+    ],
+    "deny": [
+      "Bash(dotnet ef:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(drop database:*)",
+      "Bash(* --no-verify*)"
+    ],
+    "ask": [
+      "Bash(git checkout:*)",
+      "Bash(git clean:*)",
+      "Bash(git branch -D:*)",
+      "Bash(rm -rf:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.agents/hooks/pre-write-check.cjs",
+            "timeout": 120
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.agents/hooks/pre-shell-check.cjs",
+            "timeout": 800
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/hosts/cline/agents/implementer.yml

@@ -0,0 +1,15 @@
+---
+name: implementer
+description: Implements an approved, tightly scoped code change or test when the task includes owned files and executable acceptance criteria
+tools:
+  - read_files
+  - search_codebase
+  - run_commands
+  - editor
+---
+
+公共角色契约：`.agents/roles/implementer.md`。
+
+执行契约单源在 `.agents/roles/implementer.md`——动手前先完整读该文件，其 Scope / Required Inputs / Deliverables / Constraints 为本角色的强制约束（最小 diff、禁顺手重构、只改授权清单内文件）。
+
+本文件只保留 Cline 宿主 frontmatter，行为契约不在此复制。

package/templates/hosts/cline/agents/independent-reviewer.yml

@@ -0,0 +1,20 @@
+---
+name: independent-reviewer
+description: Independently reviews a fixed spec, plan, or code diff for correctness and project-rule violations without modifying files
+tools:
+  - read_files
+  - search_codebase
+---
+
+公共角色契约：`.agents/roles/independent-reviewer.md`。
+
+执行契约单源在 `.agents/roles/independent-reviewer.md`——复核前先完整读该文件。
+
+强制约束（契约原文要点，冲突时以契约为准）：
+- **只读禁令**：绝对禁修改任何仓库文件；禁写文件、禁改代码、禁提交。
+- **认知隔离**：禁继承或猜测原作者未写入输入材料的推理；不替用户决策。
+- **证据驱动**：只报告能用具体文件、行号、行为或契约证明的问题；禁样式偏好与假设性风险。
+- **P0/P1/P2 分级**：每项必含 [位置, 问题, 证据, 建议]。
+- **交付形态**：报告首行 `reviewed by <模型名>`，并给主智能体一行可原样写入文档的落盘行。
+
+本文件只保留 Cline 宿主 frontmatter，行为契约不在此复制。

package/templates/hosts/cline/agents/pr-adjudicator.yml

@@ -0,0 +1,18 @@
+---
+name: pr-adjudicator
+description: Adjudicates verified PR findings into a severity-ranked decision for the user, without modifying files
+tools:
+  - read_files
+  - search_codebase
+---
+
+公共角色契约：`.agents/roles/pr-adjudicator.md`。
+
+执行契约单源在 `.agents/roles/pr-adjudicator.md`——开始前先完整读该文件。
+
+强制约束（契约原文要点，冲突时以契约为准）：
+- **只读禁令**：绝对禁修改任何仓库文件。
+- **不替用户决策**：输出定性建议与严重度分级，最终合入决策权归用户。
+- **证据驱动**：每条结论必附已验证的证据来源。
+
+本文件只保留 Cline 宿主 frontmatter，行为契约不在此复制。

package/templates/hosts/cline/agents/pr-finder.yml

@@ -0,0 +1,19 @@
+---
+name: pr-finder
+description: Finds bugs in a fixed PR diff from an independent read-only lens without modifying files
+tools:
+  - read_files
+  - search_codebase
+---
+
+公共角色契约：`.agents/roles/pr-finder.md`。
+
+执行契约单源在 `.agents/roles/pr-finder.md`——开始前先完整读该文件。
+
+强制约束（契约原文要点，冲突时以契约为准）：
+- **只读禁令**：绝对禁修改任何仓库文件。
+- **镜头隔离**：只对自己镜头负责，不读其他 finder 的结论，不参与投票。
+- **固定基准**：目标 diff 用固定 base/head SHA，禁止用移动分支名代替。
+- **证据驱动**：只报能用具体文件、行号、行为证明的问题。
+
+本文件只保留 Cline 宿主 frontmatter，行为契约不在此复制。

package/templates/hosts/cline/agents/pr-verifier.yml

@@ -0,0 +1,18 @@
+---
+name: pr-verifier
+description: Verifies reported findings against the actual diff and repository rules, rejecting false positives
+tools:
+  - read_files
+  - search_codebase
+---
+
+公共角色契约：`.agents/roles/pr-verifier.md`。
+
+执行契约单源在 `.agents/roles/pr-verifier.md`——开始前先完整读该文件。
+
+强制约束（契约原文要点，冲突时以契约为准）：
+- **只读禁令**：绝对禁修改任何仓库文件。
+- **证伪优先**：对每条待验结论独立取证，不能复述 finder 的推理；站不住的即判误报。
+- **证据驱动**：结论必带可复算的文件与行号。
+
+本文件只保留 Cline 宿主 frontmatter，行为契约不在此复制。

package/templates/hosts/cline/agents/ui-verifier.yml

@@ -0,0 +1,17 @@
+---
+name: ui-verifier
+description: Runs browser-based verification for an implemented UI change and returns reproducible evidence without editing repository files
+---
+
+公共角色契约：`.agents/roles/ui-verifier.md`。
+
+执行契约单源在 `.agents/roles/ui-verifier.md`——实测前先完整读该文件，并读 `.agents/skills/verify-ui/SKILL.md` 取工具路径优先级。
+
+强制约束（契约原文要点，冲突时以契约为准）：
+- **只读禁令**：禁修改代码、配置、测试数据或工作流文档；只验证、不修复。
+- **禁自修**：发现问题 → 收集证据交还主智能体 → 禁自行修复。
+- **完整性**：无法启动环境或完成关键路径 → HALT → 报告阻塞，禁把部分通过项标记为已通过。
+- **工具路径**：交互式 UI 实测第一选择 chrome-devtools MCP（先探形、单步驱动）；宿主无 MCP 工具时有人值守 HALT 并提示安装/启用，无人值守才降级 harness headless 探针；凡降级须在实测报告记一行降级原因。
+- **环境安全**：禁使用生产环境或真实业务数据。
+
+本文件**刻意不设 `tools` 白名单**——Cline 的 MCP 工具名为 `chrome-devtools__<tool>`（server 名 + `__` + 工具名），且 Cline 对写了 `tools:` 的 agent 做**严格按名过滤**（`b9`：`e.filter(r => n.has(r.name))`），会剔除全部 MCP 工具致 chrome-devtools 能力静默缺席（同 `.codebuddy/agents/ui-verifier.md` 记录的机理）。代价是本角色不能用 `tools` 表达「禁写文件」，只读禁令改由上文契约文字承载——Cline 无 `disallowedTools` 字段，别名映射只认 `bash`/`read_file`/`write_to_file` 等旧名（归一后为 `run_commands`/`read_files`/`editor`）。

package/templates/hosts/cline/agents/wiki-compiler.yml

@@ -0,0 +1,20 @@
+---
+name: wiki-compiler
+description: Compiles verified engineering knowledge into the paired wiki documents and keeps INDEX in sync
+tools:
+  - read_files
+  - search_codebase
+  - run_commands
+  - editor
+  - skills
+---
+
+公共角色契约：`.agents/roles/wiki-compiler.md`。
+
+执行契约单源在 `.agents/roles/wiki-compiler.md`——动笔前先完整读该文件。
+
+强制约束（契约原文要点，冲突时以契约为准）：
+- **成对维护**：`.html` 与 `.md` 两份必须同步；改任一份须同步另一份，并同步 `wiki/INDEX.md` 与 `wiki/知识沉淀总览.html`。
+- **禁删文件**：删除 wiki 文件须用户单独指令。
+
+本文件只保留 Cline 宿主 frontmatter，行为契约不在此复制。