agentic-flow-kit 1.8.7 → 2.1.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/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ai-native-gates
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install (if package.json)
+        run: |
+          if [ -f package.json ]; then npm install; fi
+      - name: Static gates
+        run: node .agents/scripts/verify.mjs --full
+      - name: Local gate wiring audit
+        run: node .agents/scripts/check-local-gates.mjs
+        continue-on-error: true
+      - name: Behavior eval (advisory)
+        run: node .agents/scripts/agent-eval.mjs check --advisory
+        continue-on-error: true
+      - name: Pipeline state closure
+        run: node .agents/scripts/check-pipeline-state.mjs
+        continue-on-error: true
+      - name: Injected memory budget
+        run: node .agents/scripts/memory-tier.mjs audit
+        continue-on-error: true

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/git/azure-pipelines.yml

@@ -0,0 +1,46 @@
+# Azure Pipelines — AI-native 门禁
+# 生成的默认档：main 全量、develop/PR 中档。tier=lean 时安装器不写本文件。
+trigger:
+  branches:
+    include:
+      - main
+      - develop
+pr:
+  branches:
+    include:
+      - main
+      - develop
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '22.x'
+    displayName: 'Use Node 22'
+
+  - script: |
+      if [ -f package.json ]; then
+        npm install
+      fi
+    displayName: 'Install (if package.json)'
+
+  - script: node .agents/scripts/verify.mjs --full
+    displayName: 'Static gates (verify --full)'
+
+  - script: node .agents/scripts/check-local-gates.mjs
+    displayName: 'Local gate wiring audit'
+    continueOnError: true
+
+  - script: node .agents/scripts/agent-eval.mjs check --advisory
+    displayName: 'Behavior eval (advisory; remove --advisory after baseline)'
+    continueOnError: true
+
+  - script: node .agents/scripts/check-pipeline-state.mjs
+    displayName: 'Pipeline state closure'
+    continueOnError: true
+
+  - script: node .agents/scripts/memory-tier.mjs audit
+    displayName: 'Injected memory budget'
+    continueOnError: true

package/templates/host-meta/SKILLS.md

@@ -0,0 +1,3 @@
+{{title}}
+
+{{skillsList}}

package/templates/host-meta/claude/skill-pointer.md

@@ -0,0 +1,6 @@
+---
+name: {{skillName}}
+description: {{skillDescription}}
+---
+
+{{pointer}}

package/templates/host-meta/cline/skill-index.md

@@ -0,0 +1,6 @@
+---
+name: wf-skills
+description: {{indexDescription}}
+---
+
+{{skillsList}}

package/templates/host-meta/codebuddy/skill-pointer.md

@@ -0,0 +1,6 @@
+---
+name: {{skillName}}
+description: {{skillDescription}}
+---
+
+{{pointer}}

package/templates/host-meta/commandcode/skill-index.md

@@ -0,0 +1,5 @@
+---
+description: {{indexDescription}}
+---
+
+{{skillsList}}

package/templates/host-meta/opencode/skill-pointer.md

@@ -0,0 +1,6 @@
+---
+name: {{skillName}}
+description: {{skillDescription}}
+---
+
+{{pointer}}

package/templates/host-meta/qoder/skill-index.md

@@ -0,0 +1,5 @@
+---
+description: {{indexDescription}}
+---
+
+{{skillsList}}

package/templates/host-meta/qwen/skill-index.md

@@ -0,0 +1,5 @@
+---
+description: {{indexDescription}}
+---
+
+{{skillsList}}

package/templates/host-meta/trae/skill-index.md

@@ -0,0 +1,6 @@
+---
+name: wf-skills
+description: {{indexDescription}}
+---
+
+{{skillsList}}

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