agentic-flow-kit 1.8.2 → 2.0.0

package/templates/_agents/hooks/check-index-incremental.mjs

@@ -1,48 +0,0 @@
-#!/usr/bin/env node
-// workflow/INDEX.md 漂移（增量硬拦，2026-10-12，Shipyard.Material 参考实现回灌）。
-// 检查 11 只在 check-loop --hygiene 里 WARN。关单提交不跑卫生段，索引会继续把已 closed/done 的文档列成在跑。
-// 本脚本：暂存触及 workflow 四目录、归档或 INDEX.md 时，跑生成器 --check；不一致即拒提交。
-// 未触及这些路径则跳过（引擎面提交不因陈旧索引被拦）。修复：node .agents/scripts/gen-workflow-index.mjs 后把 INDEX.md 一并暂存。
-import { spawnSync } from 'node:child_process';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const INDEX_SRC = /^(?:workflow\/(?:intents|specs|plans|incidents|archive)\/.+\.md|workflow\/INDEX\.md)$/;
-
-export function stagedTouchesIndex(files) {
-  return files.some((f) => INDEX_SRC.test(String(f).replace(/\\/g, '/')));
-}
-
-function main() {
-  const git = (args) => {
-    const r = spawnSync('git', args, { encoding: 'utf8' });
-    return { ok: !r.error && r.status === 0, out: (r.stdout || '').replace(/\r/g, '') };
-  };
-  const root = git(['rev-parse', '--show-toplevel']);
-  if (!root.ok || !root.out.trim()) {
-    console.error('索引漂移（增量）: 无法定位仓库根，提交已阻止');
-    process.exit(1);
-  }
-  const top = root.out.trim();
-  process.chdir(top);
-  const touched = git(['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only']);
-  if (!touched.ok) {
-    console.error('索引漂移（增量）: 读暂存列表失败，提交已阻止');
-    process.exit(1);
-  }
-  const files = touched.out.split('\n').filter(Boolean);
-  if (!stagedTouchesIndex(files)) process.exit(0);
-
-  const gen = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts', 'gen-workflow-index.mjs');
-  const r = spawnSync(process.execPath, [gen, '--check'], { cwd: top, stdio: 'inherit' });
-  if (r.status !== 0) {
-    console.error('索引漂移（增量）— BLOCK:');
-    console.error('  先跑 node .agents/scripts/gen-workflow-index.mjs，把 workflow/INDEX.md 一并暂存，再提交');
-    process.exit(r.status === null ? 1 : r.status);
-  }
-  process.exit(0);
-}
-
-const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMain) main();

package/templates/_agents/hooks/check-pairing-incremental.mjs

@@ -1,66 +0,0 @@
-#!/usr/bin/env node
-// 闭环配对（增量版）：本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan（L2/L3 另须同名 spec）
-// 目的：把 check-loop「配对断裂」hard-block 的发现时机从 pre-push 提前到 commit
-// （papercut 2026-09-15：maintain.md 只写「incident≡intent 免另立 intent」，未把配 plan 写成显式步骤，
-//  按文档字面执行三次 commit 全绿、push 才爆红，只能后补；
-//  2026-09-27 audit-gate-hardening 补齐 spec 档——此前只查 plan，L2/L3 缺 spec 仍要拖到 push 才爆红）
-// 口径与 check-loop 检查 1 同款分档：入口文档（intents/ incidents/ 直下 .md）↔ workflow/plans/ 同名，
-// L2/L3 级别另须 workflow/specs/ 同名；同 commit 携带 plan/spec 合法（检查的是工作区文件存在，staged 新建同样命中）。
-// 自 sh 版移植 node（2026-10-08 门禁去 sh 化第二批；2026-10-13 自 Shipyard.Material 参考实现回灌）——语义逐条对齐。
-// 已知边界（沿 sh 版）：legacy 豁免与级别读取均基于工作区文件而非暂存 blob——add 后又改工作区时
-// 可能误豁免/误拦（逐文件取 blob 的 fork 成本大于收益，接受）。
-// git 调用带 `-c core.quotepath=off`：quotepath 默认 true 时非 ASCII 路径被引号转义，
-// workflow/ 前缀匹配失配 → 门禁静默跳过（2026-09-27 gate-coverage 教训）。
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-
-const git = (args) => {
-  const r = spawnSync('git', args, { encoding: 'utf8' });
-  return { ok: !r.error && r.status === 0, out: (r.stdout || '').trim() };
-};
-const root = git(['rev-parse', '--show-toplevel']);
-if (!root.ok) process.exit(1);
-process.chdir(root.out);
-
-const staged = git(['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only', '--diff-filter=ACMR']);
-if (!staged.ok) process.exit(1);
-const entries = staged.out.split('\n').filter((f) => /^workflow\/(intents|incidents)\/[^/]+\.md$/.test(f) && !f.endsWith('_TEMPLATE.md'));
-
-let fail = 0;
-const block = (lines) => { console.log('闭环配对（增量）— BLOCK:'); for (const l of lines) console.log('  ' + l); fail = 1; };
-
-for (const f of entries) {
-  // 闭环引擎启用前的回填件带「流程: legacy」豁免配对检查（与 check-loop 同口径）
-  let legacy = false, lvl = '';
-  try {
-    for (const line of fs.readFileSync(f, 'utf8').split(/\r?\n/)) {
-      if (line.startsWith('流程: legacy')) legacy = true;
-      const m = /^级别:\s*(.*)$/.exec(line);
-      if (m && lvl === '') lvl = m[1].trim();
-      if (legacy && lvl !== '') break;
-    }
-  } catch { /* 读不到按未豁免处理（沿 sh 版 grep 失败即不豁免的语义） */ }
-  if (legacy) continue;
-  const base = path.basename(f, '.md');
-  if (!fs.existsSync(path.join('workflow', 'plans', `${base}.md`))) {
-    block([
-      `入口缺同名 plan: ${f}（应在 workflow/plans/${base}.md）`,
-      'L1 用 fill-plan.mjs --level L1（入口/改动方案/约束与风险/验证计划/验收标准），不另立 intent',
-    ]);
-  }
-  if (lvl === 'L2' || lvl === 'L3') {
-    if (!fs.existsSync(path.join('workflow', 'specs', `${base}.md`))) {
-      block([
-        `入口缺同名 spec: ${f}（级别 ${lvl} 须三件套，应在 workflow/specs/${base}.md）`,
-        '与 pre-push check-loop 检查 1 同口径——先起草 spec 走 design.md，再提交',
-      ]);
-    }
-  }
-}
-
-if (fail !== 0) {
-  console.error('pre-commit: 入口文档配对不全（plan / L2-L3 spec），提交已阻止（与 pre-push check-loop 同口径，发现时机提前到 commit）');
-}
-process.exit(fail);

package/templates/_agents/hooks/check-wiki-ledger.mjs

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-// wiki 台账一致性（增量版）：本次暂存触及 wiki/ 时跑 verify 三方校验（磁盘 ↔ INDEX ↔ 看板 DATA）
-// 目的：给「登记动作」装触发点——verify 此前无任何钩子调用，只能靠「触及 wiki 时手跑」的文字纪律
-// （incident 2026-09-16-wiki-drift-and-verifier-gaps 认定的根因）；本脚本把发现时机提前到 commit。
-// 口径与 .agents/scripts/verify-wiki-consistency.mjs 一致：活层新增/删除/移动未登记、数据维护批次目录未入台账即拦。
-// 自 sh 版移植 node（2026-10-08 门禁去 sh 化第二批；2026-10-13 自 Shipyard.Material 参考实现回灌）——语义逐条对齐。
-// 注意 git 调用带 `-c core.quotepath=off`：quotepath 默认 true 时中文路径被转义加引号，^wiki/ 前缀
-// 匹配失配 → 门禁静默跳过（2026-09-27 gate-coverage 教训）。
-import { spawnSync } from 'node:child_process';
-import path from 'node:path';
-import process from 'node:process';
-
-const git = (args) => {
-  const r = spawnSync('git', args, { encoding: 'utf8' });
-  return { ok: !r.error && r.status === 0, out: (r.stdout || '').trim() };
-};
-const root = git(['rev-parse', '--show-toplevel']);
-if (!root.ok) process.exit(1);
-process.chdir(root.out);
-
-const touched = git(['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only']);
-if (!touched.ok || !touched.out.split('\n').some((f) => f.startsWith('wiki/'))) process.exit(0);
-
-const r = spawnSync(process.execPath, [path.join('.agents', 'scripts', 'verify-wiki-consistency.mjs')], { stdio: 'inherit' });
-if (r.status !== 0) {
-  console.log('wiki 台账（增量）— BLOCK:');
-  console.log('  先跑 node .agents/scripts/gen-wiki-board.mjs 补 INDEX/看板（或补 wiki/数据维护/README.md 登记行），再原路重试提交');
-  process.exit(1);
-}
-process.exit(0);

package/templates/_agents/hooks/commit-check.cjs

@@ -1,193 +0,0 @@
-// commit-check: git commit 前置验证（agentic-flow-kit 通用版）
-// 1) 敏感信息扫描（暂存区新增行含疑似密钥 -> BLOCK）
-// 2) 条件构建验证（按 .agents/hooks/commit-check.config.json 的 builds 配置；--full 不做 ext/prefix 裁剪，仍尊重 when）
-// 3) 质量检测（config.checks：lint / 类型检查 / vet 等秒级确定性检查；--full 不做 ext/prefix 裁剪，仍尊重 when）
-// 旗标（2026-10-16 构建门后移 pre-push，自源仓 2ff869a9 回灌）：
-//   --no-build：跳过段 2 条件构建——pre-commit 常规提交用（提交内环提速）；构建在 pre-push 按推送范围
-//     执法，合并提交仍走 --full 全量构建（合并结果是没人验证过的新状态）。
-//   --range <old> <new>：推送范围模式（pre-push 用）——文件面取 git diff --name-only old new；
-//     old 为全零 sha（新分支首推）= 全量匹配语义（等价 --full 的构建面）；段 1 敏感扫描跳过
-//     （逐提交时刻 pre-commit 已扫，范围重扫无增量价值）。默认（无旗标）暂存区模式行为不变。
-// config 由 flow-kit init 按技术栈生成初值，项目可自行增改；缺失或无 builds/checks 时跳过对应段。
-// 配置示例（.agents/hooks/commit-check.config.json）：
-//   {
-//     "knownPatterns": ["admin\\/123", "my-project-seed"],       // 项目已知种子/代码标识符白名单（正则源，i 标志）
-//     "builds": [
-//       { "name": "backend",  "command": "dotnet build", "ext": [".cs", ".sln", ".csproj"] },
-//       { "name": "frontend", "command": "npm run build", "ext": [".ts", ".tsx", ".vue", ".js", ".jsx"],
-//         "cwd": "frontend",
-//         "lockPattern": "MSB3026|MSB3027",                        // 可选：命中时按 lockHint 提示（文件锁类「与代码无关」失败）
-//         "lockHint": "构建被文件锁拦下——本地运行中的进程正占用产物，停进程后重试" },
-//       { "name": "docs-site", "command": "npm run build", "prefix": "docs/", "cwd": "docs" }   // prefix 可选：路径前缀触发
-//     ],
-//     "checks": [
-//       { "name": "typecheck", "command": "npx tsc --noEmit", "ext": [".ts", ".tsx"], "when": ["tsconfig.json"] },
-//       { "name": "lint",      "command": "npx eslint .", "ext": [".ts", ".js"], "when": ["eslint.config.js", ".eslintrc.json"] }
-//     ]
-//   }
-// builds/checks 触发判定（对暂存文件，.agents/ 与 .githooks/ 自身变更不计）：`ext 任一匹配 OR prefix 前缀命中`。
-//   - 只有 ext：按扩展名全局触发（跨目录，适合语言型触发——仓库里该扩展名基本只属于该构建）；
-//   - 只有 prefix：该前缀下任何文件触发（目录型触发——如 monorepo 子包，仓库其他位置的相同扩展名不触发）；
-//   - 两者同配为 OR 并集而非 AND 交集——要「前缀内的特定扩展名」请只配 prefix（目录内文档变更多跑一次构建，方向安全）。
-// when（builds 与 checks 共用）：数组任一满足才启用，无 when 字段 = 无条件启用。
-//   - 路径或尾部 * 一层通配（如 "*.sln"）：相对仓库根做存在性判断；
-//   - pkg:<点分路径>（如 pkg:scripts.build）：读该项 cwd（缺省仓库根）的 package.json，
-//     沿路径取值，非空字符串才算满足。
-//   没有对应配置的项目自动跳过并提示，不 fail-closed 误拦。--full 同样尊重 when。
-const { execSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-process.chdir(path.resolve(__dirname, '../..'));
-
-function sh(cmd, cwd) {
-  try {
-    execSync(cmd, { stdio: 'pipe', encoding: 'utf8', cwd: cwd || undefined });
-    return { ok: true, out: '' };
-  } catch (e) {
-    return { ok: false, out: String((e.stdout || '') + (e.stderr || '')) };
-  }
-}
-
-// --- 模式旗标（2026-10-16 构建门后移 pre-push；sha 经 git 管道来仍做白名单校验——信任边界） ---
-const NO_BUILD = process.argv.includes('--no-build');
-const rangeIdx = process.argv.indexOf('--range');
-const RANGE = rangeIdx >= 0 ? process.argv.slice(rangeIdx + 1, rangeIdx + 3) : null;
-if (RANGE && (RANGE.length < 2 || !/^[0-9a-f]{4,40}$/i.test(RANGE[0]) || !/^[0-9a-f]{4,40}$/i.test(RANGE[1]))) {
-  console.log(`BLOCK: --range 参数须为两个 git sha（现「${(RANGE || []).join(' ')}」）`);
-  process.exit(1);
-}
-// 全零 old = 新分支首推：git diff 对全零 sha 无从执行，且本就取全量匹配语义——文件面置空即可
-const RANGE_ZERO_OLD = RANGE !== null && /^0+$/.test(RANGE[0]);
-
-let staged = [];
-try {
-  const listCmd = !RANGE ? 'git diff --cached --name-only'
-    : RANGE_ZERO_OLD ? null
-    : `git diff --name-only ${RANGE[0]} ${RANGE[1]}`;
-  staged = listCmd === null ? []
-    : execSync(listCmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
-      .split('\n').map(s => s.trim()).filter(Boolean);
-} catch (e) {
-  console.log('BLOCK: 无法读取变更文件面（git diff 失败）');
-  process.exit(1);
-}
-
-// --- 0) 项目配置（可选） ---
-let config = { knownPatterns: [], builds: [] };
-try {
-  const raw = JSON.parse(fs.readFileSync('.agents/hooks/commit-check.config.json', 'utf8'));
-  config = { ...config, ...raw };
-} catch (e) { /* 无配置 = 敏感扫描用基线白名单 + 跳过构建验证 */ }
-
-// --- 1) 敏感信息扫描：暂存区新增行是否含疑似密钥（只认带引号的字符串字面量；排除类型/空值关键字） ---
-const SECRET = /(password|passwd|pwd|secret|token|apikey|api[_ -]?key|connectionstring|server=|bearer)["']?\s*[:=]\s*["'](?!["']?(string|number|boolean|unknown|any|never|void|object|null|undefined|true|false)\b)[^"'\r\n]{6,}["']/i;
-// 判据/白名单自身的定义行长得就像密钥赋值，须自豁免
-const SELF = /const (SECRET|KNOWN) = \//i;
-// KNOWN：项目已知种子与代码标识符白名单（config.knownPatterns 注入；本文件基线为空——通用包不带项目种子）
-let KNOWN = null;
-if (Array.isArray(config.knownPatterns) && config.knownPatterns.length) {
-  KNOWN = new RegExp(config.knownPatterns.join('|'), 'i');
-}
-let diffText = '';
-try {
-  diffText = execSync('git diff --cached', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-} catch (e) { /* 空暂存 */ }
-const added = diffText.split('\n').filter(l => l.startsWith('+') && !l.startsWith('+++'));
-const hits = added.filter(l => SECRET.test(l) && !(KNOWN && KNOWN.test(l)) && !SELF.test(l));
-  if (hits.length) {
-    console.log('BLOCK: 暂存区疑似包含敏感信息（密钥/连接串/令牌），请检查:\n' + hits.slice(0, 5).join('\n'));
-    process.exit(1);
-  }
-  if (RANGE) console.log('SKIP: --range 模式跳过敏感扫描（逐提交时刻 pre-commit 已扫，2026-10-16 构建门后移）');
-
-// --- 2) 条件构建验证 ---
-// --full：合并提交（pre-merge-commit / 冲突解决后手动 commit）使用——合并结果是没人验证过的新状态，
-// 按 ext/prefix 裁剪可能漏掉需要重跑的一侧，故不做路径裁剪。when 仍生效：没有对应能力就不跑。
-// --range 全零 old sha（新分支首推）同取全量匹配语义。
-// 引擎自身文件（.agents/、.githooks/）不参与构建匹配——工作流引擎不是项目构建产物。
-const FULL = process.argv.includes('--full') || RANGE_ZERO_OLD;
-const stagedForBuild = staged.filter(f => !f.startsWith('.agents/') && !f.startsWith('.githooks/'));
-
-// whenSatisfied：任一谓词满足即启用。pkg: 读 cwd 下的 package.json；其余谓词相对仓库根。
-function whenItem(w, cwd) {
-  if (typeof w === 'string' && w.startsWith('pkg:')) {
-    const keys = w.slice(4).split('.').filter(Boolean);
-    if (!keys.length) return false;
-    const pkgPath = path.join(cwd || '.', 'package.json');
-    let pkg;
-    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch (e) { return false; }
-    let cur = pkg;
-    for (const k of keys) {
-      if (cur == null || typeof cur !== 'object' || !Object.prototype.hasOwnProperty.call(cur, k)) return false;
-      cur = cur[k];
-    }
-    return typeof cur === 'string' && cur.trim() !== '';
-  }
-  const star = String(w).indexOf('*');
-  if (star < 0) return fs.existsSync(w);
-  const suffix = w.slice(star + 1);
-  const dir = path.dirname(w.slice(0, star)) || '.';
-  try { return fs.readdirSync(dir).some((f) => f.endsWith(suffix)); } catch (e) { return false; }
-}
-function whenSatisfied(when, cwd) {
-  if (!when) return true;
-  const list = Array.isArray(when) ? when : [when];
-  return list.some((w) => whenItem(w, cwd));
-}
-function skipWhen(kind, item) {
-  const shown = Array.isArray(item.when) ? item.when.join(' / ') : item.when;
-  console.log(`SKIP: ${item.name}（未找到 ${shown}，跳过${kind}——配置好后自动启用）`);
-}
-
-if (NO_BUILD) {
-  console.log('SKIP: --no-build（2026-10-16 构建门后移 pre-push——常规提交不再构建，推送时按范围执法）');
-} else {
-  let consideredBuild = false;
-  for (const b of (config.builds || [])) {
-    if (!b || !b.command) continue;
-    const exts = Array.isArray(b.ext) ? b.ext : [];
-    const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (b.prefix ? f.startsWith(b.prefix) : false));
-    if (!match) continue;
-    consideredBuild = true;
-    if (!whenSatisfied(b.when, b.cwd)) { skipWhen('构建', b); continue; }
-    const r = sh(b.command, b.cwd);
-    if (!r.ok) {
-      if (b.lockPattern && new RegExp(b.lockPattern).test(r.out)) {
-        console.log(`BLOCK: ${b.name} 构建被文件锁拦下（与代码无关）。${b.lockHint || '停掉占用进程后原路重试'}\n` +
-          '锁冲突行：\n' + r.out.split(/\r?\n/).filter(l => new RegExp(b.lockPattern).test(l)).slice(0, 3).join('\n'));
-      } else {
-        console.log(`BLOCK: ${b.name} 构建失败（${b.command}）\n` + r.out.slice(0, 1500));
-      }
-      process.exit(1);
-    }
-    console.log(`OK: ${b.name} 构建通过（${b.command}）`);
-  }
-  if (!consideredBuild) {
-    console.log(config.builds && config.builds.length
-      ? 'SKIP: 无匹配的源码变更，跳过构建验证'
-      : 'SKIP: 未配置 builds（.agents/hooks/commit-check.config.json），跳过构建验证');
-  }
-}
-
-// --- 3) 质量检测（checks：lint / 类型检查 / vet 等秒级确定性检查；测试不放这里——关单在 test.md 阶段门） ---
-let ranCheck = false;
-for (const c of (config.checks || [])) {
-  if (!c || !c.command) continue;
-  const exts = Array.isArray(c.ext) ? c.ext : [];
-  const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (c.prefix ? f.startsWith(c.prefix) : false));
-  if (!match) continue;
-  ranCheck = true;
-  if (!whenSatisfied(c.when, c.cwd)) { skipWhen('质量检查', c); continue; }
-  const r = sh(c.command, c.cwd);
-  if (!r.ok) {
-    console.log(`BLOCK: ${c.name} 质量检查未通过（${c.command}）\n` + r.out.slice(0, 1200));
-    process.exit(1);
-  }
-  console.log(`OK: ${c.name} 质量检查通过（${c.command}）`);
-}
-if (!ranCheck && config.checks && config.checks.length) {
-  console.log('SKIP: 无匹配的源码变更，跳过质量检测');
-}
-
-console.log('COMMIT_CHECK_OK');

package/templates/_agents/hooks/local-pre-commit

@@ -1,6 +0,0 @@
-#!/bin/sh
-# 项目门禁挂载点（.githooks/pre-commit 在通用门禁之后执行本文件；返回非零即阻断提交）
-# 把项目专属门禁逐行加在这里；npx agentic-flow-kit add-gate <门禁> 会自动接线（手动示例：）：
-#   sh .agents/hooks/check-architecture.sh
-# set -e：任一门禁非零即中止本脚本（退出码透传给 pre-commit 阻断提交）——不要在末尾加 exit 0
-set -e

package/templates/_agents/lane-surfaces.txt

@@ -1,17 +0,0 @@
-# L2 触达面清单（单源：本文件——check-lane-surface.mjs 检查 A 共读，pre-commit「泳道完整性」门禁）
-# 格式：每行一条 ERE（grep -E 兼容），匹配暂存文件的仓库相对路径（/ 分隔）。
-#   # 注释与空行忽略；本文件缺失或清单为空 = 检查跳过（装户无感升级）。
-#   正则语法错误行 → 门禁 fail-closed 阻断（防静默空洞，修配置后重试）。
-# 语义：命中任一模式 = 本次改动触及「一处定义、多处消费」的契约 / 规则面（L2 触达面，
-#   判据单源见 .agents/scripts/level-criteria.mjs 的 L2_SURFACES）。此时须有活跃（draft/approved / open/fixed）
-#   L2/L3 入口罩着；活跃入口全为 L1 会被 pre-commit「触达面判低」拦截（三选修法见门禁消息）。
-#   无任何活跃入口时仅 advisory——docs / bootstrap 豁免类改动（new-task.md §intent 豁免）不受阻。
-# 漏登面审计：node .agents/scripts/lane-surface-audit.mjs（advisory，恒 exit 0）——近窗口（默认 30 天）
-#   L2/L3 任务反复触及（≥3 个不同入口文档）却无文件被本清单命中的目录 = 候选漏登面，供人工评估补登；
-#   月度手跑，改共享契约频繁期可随时跑（候选 ≠ 必登——高频触及 ≠ 契约面，机器不猜语义）。
-# 本仓默认面（引擎 / 契约面，行为承载目录——commands/roles 纯提示文本属 docs 级不列入；按项目自行改）：
-^templates/
-^\.agents/(scripts|hooks)/
-^\.githooks/
-^bin/
-^modules/

package/templates/_agents/level-hints.txt

@@ -1,30 +0,0 @@
-# 风险级别路径提示清单（单源消费方：templates/_agents/scripts/level-criteria.mjs）
-#
-# 用途：登记「哪些路径一碰就**至少**是 L2 / L3」。定级是**意图面**的语义判定（「一处定义、多处消费」），
-#       机器判不了语义；但「路径下限」可以登记，避免明显高风险的改动被拍脑袋判成 L1。
-#       与 lane-surfaces.txt 的分工：那是**提交面**的触达判据（改这些面须有活跃 L2/L3 入口），
-#       本文件是**意图面**的档位提示（改这些面就该按更高档走）。两者不同档，各司其职。
-#
-# 格式：每行一条 `<档位> <ERE>`，ERE 为 grep -E 兼容正则，匹配仓库相对路径（/ 分隔）。
-#   档位**只收 L2 / L3**：本清单登记的是「一碰就至少是中/高风险面」的下限。L1 不构成门槛（L0 已退役），
-#   登记了只会让提交面判低门（L2 触达面门）对无关改动出手——那正是要避免的噪声。
-#   **ERE 与注释必须分两行**：写 `L3 ^a\.sql$  # 迁移 SQL` 会把 `# 迁移 SQL` 编进正则，
-#   若含 $ 锚点该条就永不命中，且不报任何错（路径下限与提交面兜底同时静默失效）。
-#   确需匹配路径里的 # 时写 \#。非法档位 / 行内注释 / 正则语法错 → **fail-loud 抛错**
-#   （写错配置比没配置危险：没配置会提示补，写错会误判）。
-#   # 注释与空行忽略；本文件缺失或清单为空 = 纯语义定级（判据面全程静默，不阻断）。
-#
-# 默认留空（刻意）：本清单内容是**项目私有**的——按你自己的代码布局登记，照抄别人的清单等于没登记。
-# 建议起步：从「改什么几乎必然是 L2/L3」的高频面挑 3~5 条先登记，跑一段时间再补。
-#
-# ---- 示例（取消注释并按项目实际路径改写；本仓为 node 包源，下例仅示意形态）----
-# # 迁移 SQL（注释单独成行，不要接在 ERE 后面）
-# L3 ^src/db/migrations/.*\.sql$
-# # schema 定义
-# L3 ^src/db/schema/
-# # 认证与中间件管线 / DI 链
-# L3 ^(src/(auth|middleware)/|src/.*\.(auth|di)\.(ts|js)$)
-# # 共享契约（DTO / 接口签名）
-# L2 ^src/contracts/
-# # 编码权威（取号 / 命名规则生成器）
-# L2 ^src/coding/

package/templates/_agents/loop/papercut-debt/DESIGN.md

@@ -1,112 +0,0 @@
-# papercut-debt 控制回路 — 设计（2026-10-07 拍板；B10a 自 Shipyard.Material 回灌）
-
-> 本文件是回路的**设计单一真相源**。传感器 / 控制器 / 执行器技能 / 记忆文件均按此实现，改设计先改本文件。
-> 范围：把 `workflow/papercuts.md` 的未升级存量债驱动到 0。执行器为**对话内手动触发**（kit 不为回路接线 CI/定时）。
-
-## 1. 设定点（Set point）
-
-**`workflow/papercuts.md` 中未消债条目数 → 0。**
-
-- **判定口径（单源，本文件）**：
-  - **已消债（settled）** = 该行含 `✅`（真修完）**或** 含 `⏸ 暂缓（日期）：理由`（人读过、判失效）。
-  - **未消债（debt）** = 其余，即 `debt = 总数 − settled`。
-  - `⏸ 暂缓` **无理由者仍计债** —— 堵"标个符号清零"的路，迫使人真读一遍。
-  - **环境约束类（`[env]` 前缀）**：「位置」列以 `[env]` 开头（外层可带反引号包裹，传感器兼容）的行**不进债池**（`scan()` 不返回，控制器 import 债池数组天然不选），单列 `envPending`（仅未 settled 的）。清账两路径：环境前提复测消失 → `⏸ 暂缓（日期）：前提已消失`；定性实为代码缺陷 → 去前缀转正回债池。理由：环境自愈不该由回路轮询发现（源仓首轮实证：pypi 恢复后自愈的环境条目，却占 debt 名额等人工定性一轮——留痕在包源仓 git 历史与 CHANGELOG）。
-  - 两类分开计数（`resolved` / `deferredReasoned`），避免"暂缓"冒充"修完"。
-- 终态：全部条目 settled。**"暂缓"是合法终态，但必须有人写理由。**
-- 基线：装户首次跑传感器时的 `debt` 读数即基线，随后每轮 `debt` 恰好 -1。装户侧不预填数字。
-
-> **首轮修正（设计教训，单源保留）**：初版口径只有 `✅` 判债、`⏸` 不消债。后果是执行器走"判失效"分支（写 `⏸`）后 `debt` 不减，完成判据"debt 恰好 -1"永远达不到，且控制器下一轮仍选中同一条 → **回路空转**。现口径按上表，`settled` 由传感器单源判定、控制器 import 复用（两处各判一次必然漂移，见 §3 末）。
-
-为什么选它（三条依据）：
-
-1. **计数客观**：`papercuts.md` 是人写的自由文本表格，但"是否已升级"是二值事实，解析成本低、复跑稳定。
-2. **改动面天然是文档**：每条 papercut 的"拟修"列指向的多是 `.agents/commands/`、`.agents/skills/`、`.githooks/` 下的提示文本与脚本 —— 与回路执行器边界（文档面）**天然对齐**，不需人为收窄。
-3. **不撞人工门**：`papercuts.md` 是普通台账，**不走 `confirm-doc` 状态机**（不同于 intent/spec/plan），所以回路可以无人值守跑而不会卡在人工确认点。
-
-不选的候选与理由属**装户实测数据**（源仓实例：回归清单未勾项、常驻面体积瘦身、check-loop 存量 warning——留痕在包源仓 git 历史与 CHANGELOG）。装户立回路时按同原则自评：单轮以小时计的、改 AI 行为指令的、性价比最低的候选不进本回路。
-
-## 2. 传感器（Sensor）
-
-**脚本**：`.agents/scripts/papercut-debt-sensor.mjs`
-**输出**：`--json` 时给结构化 JSON；默认给人读的中文摘要。退出码恒 0（**测量失败不该阻断回路**，但会显式打印 ERROR 行）。
-
-测量口径：
-
-| 字段 | 含义 |
-|---|---|
-| `unresolved` | 未升级条目数组，每项含 `line` / `date` / `location` / `symptom` / `proposedFix` / `hits`（scope 由控制器 §3 判定，不在此列） |
-| `resolved` | 已升级条目数 |
-| `total` | 台账数据行总数（排除表头与分隔行） |
-| `debt` | `unresolved.length` —— 设定点的当前误差 |
-
-关键设计约束：
-
-- **零子进程**。不 spawn git / node。理由（源仓实测，留痕在包源仓 git 历史与 CHANGELOG）：曾有托管 Node 环境 `spawnSync` 对**任意**可执行文件（含 node 自身）返回 `EBUSY`，任何依赖 git 历史的传感器在该环境不可用——已有 `check-loop.mjs` 就是这么崩的。零子进程设计保留：传感器不依赖子进程比依赖更稳，且免受环境回退影响。
-- **CRLF 容忍**。台账检出为 CRLF（全局 `core.autocrlf=true`），按 `split(/\r?\n/)` 切行，**禁止依赖行尾格式**。
-- **管道符安全**。单元格内可能含 `|`（代码片段），按"切分后多于 6 段则把中间段并回症状列"处理，取前 3 列 + 末列。
-- **失效路径不阻塞**。对每条的"位置"列抽出形如 `.agents/…` / `wiki/…` 的路径并检查存在性；不存在只标 `stale: true`，不排除该条 —— 台账记的是历史事实，路径后来被重命名/删除是常态，不等于债已消。
-- **分片感知**（kit 侧随 ledger-shards 落地）：读侧走 `readLedgerText(root,'papercuts')`（主台账 ∪ `workflow/papercuts.d/*.md`），无分片时等价原读法——传感器零额外逻辑，口径不变。
-
-## 3. 控制器（Controller）
-
-**脚本**：`.agents/scripts/papercut-debt-controller.mjs`
-**输入**：`papercut-debt-sensor.mjs --json` 的输出（或自己调传感器）。
-**输出**：本轮唯一目标（top-1），markdown 片段，直接拼进执行器提示词。
-
-排序键（**确定性，无随机、无 LLM 判断**）：
-
-1. **命中次数降序** —— 台账文件头自己的规则："同一文件命中第 2 次或用户点名时，升级为 docs 修复 commit"。`第 N 次命中` 从症状/拟修文本中正则抽取。
-2. **日期降序** —— 同命中次数下，日期新的优先（近期痛点更可能仍成立）。
-3. **原行序升序** —— 完全平手时按台账原始顺序，保证结果可复现。
-
-**Scope gate（出选前过滤）**：`拟修` 明确指向 `backend/` `frontend/` `tests/` `wiki/` `sqlcmd` `db_tool`，或文本含 `数据库` / `DDL` / `DROP` 的条目，本轮跳过并列为 `skipped-out-of-scope`。记入输出，由用户决定是否授权。执行器只改文档面。指向业务代码或连库的条目超出授权。
-
-**单轮只取 1 条。** L2/L3 要求独立复核，控制器不得一次给出 3 条。
-
-**口径复用（硬约束）**：控制器**不得复制** `✅` / `⏸` / `hits` / `stale` 的任何判定正则，一律 `import { scan } from './papercut-debt-sensor.mjs'`。控制器只负责排序与 scope gate。理由（源仓首轮实证，留痕在包源仓 git 历史与 CHANGELOG）：两处各判一次必然漂移——初版传感器按 `✅` 判债、控制器也按 `✅` 选目标，导致已 `⏸` 的条目被反复选中。
-
-## 4. 执行器（Actuator）
-
-**技能**：`.agents/skills/papercut-fix/SKILL.md`（装副本随 `.agents/skills/` 分发）。
-**触发**：你说"跑一轮 papercut 回路"。
-**验证门**（改动后必跑，全部零 spawn 或纯本地）：
-
-```bash
-node .agents/scripts/check-loop.mjs          # 闭环骨架（实证留痕在包源仓 git 历史与 CHANGELOG）
-node .agents/scripts/papercut-debt-sensor.mjs --json   # debt 应恰好 -1
-```
-
-> **注意**：`verify.mjs` 默认不在本回路跑 —— 回路只动台账与技能文件（文档面），`verify.mjs` 含构建/测试（源码面，按装户技术栈），与 papercut 回路边界无关，回路收尾以传感器计数核验为准。需要关单凭证时直跑 `node .agents/scripts/verify.mjs`（全绿自动落 verifications.jsonl）。
-
-**金样（golden patterns）**，已固化进技能：
-
-- 台账写入**一律用 Edit 工具**（源仓实证 papercut：`node -e` 批量 replace 遇 CRLF 静默无操作、假落账——留痕在包源仓 git 历史与 CHANGELOG）。
-- 写后**必 grep 回读验证**再报成功。
-- 标 ✅ 时**追加**升级记录（日期 + commit），不删原"拟修"文本 —— 原文本是复发时的对照物。
-- 改动 `.agents/commands/` 后必看 `.agents/rule-budgets.txt` 的体积上限（常驻面只增不减，一进一出；机器门 `node .agents/scripts/rule-budget.mjs --staged`）。
-
-## 5. 扰动与阻尼器（Disturbances / Dampener）
-
-**扰动源**（通用形态）：
-
-- 用户并发提交：回路运行期间，用户可能修改同一文件。
-- 生成物漂移 —— `workflow/INDEX.md`、`workflow/metrics.md`、`gen-wiki-board` 产物会随任何状态变更而重生成。
-- 工具链升级 —— kit bump 会重写 `.agents/` 装副本，台账里的"拟修"可能已失效。
-
-**阻尼器（已存在，不另建）**：`.githooks/pre-commit` 门禁（常驻面体积预算 `rule-budget --staged` 硬拦等）+ `pre-push` 的 `check-loop` hard-block。**新条目带 `⏸ 暂缓` 而无理由**、或同一行被并发改写压行，都会在这两道门上现形。回路**不新增任何门禁** —— 现有门禁已足够挡住"回路把台账改坏"。
-
-## 6. 人在环上（Human on the loop）
-
-- **记忆文件**：装户自持（owned 面参考 `.agents/notes/`）——常驻反馈（永久范围排除、已知失效区、reviewer 意见）。每轮在控制器之后、提示词之前注入。**只写耐久规则，不写单轮日志**。
-- **人工放行**：回路不自动 commit、不 push。产出 diff 后停止，等待用户明确放行。
-- **`/iterate` 不实现**。追加范围或暂缓须由用户在对话中逐条给出，例如「修第 3 条」或「这条暂缓，理由 X」。
-
-## 7. 流控（Flow control）
-
-**在途判据**：工作区存在本回路产生的未提交 diff。手动触发时同一工作区只跑一轮，不另绑远端评审流。`--dry-run` 只输出目标清单，不改文件。
-
-## 8. 历史阻塞与豁免（源仓实证，单源保留结论）
-
-1. **回路脚本落 `.agents/scripts/` 是否命中 L2 触达面**：不命中——`check-lane-surface.mjs` 在无活跃 L2/L3 入口时只出 advisory、exit 0 放行（**规则**：无活跃入口即放行）。**结论：不必为回路另立 intent**；若日后 `.agents/scripts/` 确有 L2 语义改动被拦，再按 `new-task.md` 立入口。实测过程留痕在包源仓 git 历史与 CHANGELOG。
-2. **依赖 git 历史的传感器在本机必崩**（EBUSY）：以零子进程设计规避（§2），不做环境假设。源仓后来环境升级后该崩溃消失，但零子进程约束不回退——传感器不依赖子进程比依赖更稳。

package/templates/_agents/mechanism-registry.md

@@ -1,27 +0,0 @@
-# 机制使用量台账 (Mechanism Usage Registry)
-
-> 门禁棘轮的出口：每个门禁机制的「触发统计口径 + 退役阈值 + 状态」单源登记于此。
-> **台账的目的不是记录而是强制处置**：新增门禁机制须登记一行（一进一出，并点名它替代/合并的
-> 既有机制，无替代则说明增量理由）；机制退役时状态改「已退役」并在最近触发列留档；
-> 低频机制按退役阈值降级。
-> 列序固定：机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限。
-> 本表归装户自持运营（sync 永不覆盖，同 metric-claims.txt 口径）；kit 引擎做 WARN 级格式校验
-> （check-loop 检查 22：列数 / 状态枚举 / 待退役处置期限——advisory 不阻断，永不 hard），
-> 对账纪律靠下方「维护纪律」人工执行；判定数据面由 check-loop 每次真实运行自动落账到
-> `.agents/judgments.jsonl`（judgment-ledger，本地 gitignore），月度聚合经 agg-judgments.mjs 查账。
-
-| 机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限 |
-|---|---|---|---|---|---|---|
-| 确认指纹对账（示例行） | check-loop 检查 15 | hard「指纹不配对/确认内容漂移」计数（月，经 agg-judgments 查判定流水） | 不退役（防伪造确认主干） | 示例：建门留档见包源仓 git 历史与 CHANGELOG | 现役 | — |
-| 触达面判低门（示例行） | check-lane-surface（pre-commit/CI 泳道完整性） | hard「触达面判低/产品契约面」计数（月） | 不退役（级别闭环主干） | 示例：在用 | 现役 | — |
-
-> 以上两行为**示例行**，只示范登记口径，不参与装户对账；装户按自有机制增删行，
-> 首次对账时可将示例行替换为真实运营数据。
-
-## 维护纪律
-
-- **一进一出**：新增门禁机制必须同时在本表登记，并点名它替代/合并的既有机制（无替代则说明增量理由）。
-- **月度对账**：每月初按「触发统计口径」列刷新计数（半自动：`node .agents/scripts/agg-judgments.mjs`
-  查判定流水 `.agents/judgments.jsonl`——check-loop 每次真实运行自动落账，替代人工 grep 输出；
-  git log 统计口径不变）；达到阈值的行改「待退役」并填处置期限。
-- **退役动作**：状态改「已退役」当日删除机制代码 + 其测试 + 本表更新，同一提交完成（不留死代码）。

package/templates/_agents/metric-claims.txt

@@ -1,81 +0,0 @@
-# 量化断言「指标签名」单源登记表（check-loop 检查 16 共读）
-#
-# 背景（2026-09-28 claim-exceeds-fix）：结论文档里跨文档引用的量化值若各自手写，
-# 极易在事实变更后不同步——本仓已实证：同一指标在一处改了、另一处没改，
-# 而「五处文件同步」这句话本身无人核对（该单真正被门禁抓住的方式，是事后人工复核）。
-# 本表把「哪个指标、当前取值多少」收敛为单源，供 check-loop 检查 16 对账。
-#
-# 用法：活跃态文档（draft/approved/open）引用某个已登记指标时，按**签名形态**书写，
-# 检查 16 会实时取数比对。签名形态：\{\{指标名\}\}（双花括号包裹指标名，小写点分）。
-#   例（下面是「讲语法」，故加反斜杠转义；**写真断言时不加反斜杠**）：
-#     本仓台账共 \{\{ledger.lines\}\} 行，其中无 batch 字段 \{\{ledger.linesWithoutBatch\}\} 行。
-# 写作时**不要手写数字**——写完跑 check-loop，工具会把实时值填进提示里供你替换。
-# 转义按「逐个出现」生效：同一行里 \{\{x\}\} 是示意、\{\{y\}\} 是真断言时，只豁免前者。
-# （本例的指标名曾写成 ledger.total / ledger.noBatch 两个**并不存在**的名字——本表不被
-#   检查 16 扫描（它是 .txt 非 .md），故这类笔误不会被自动抓到，只能靠复核。已据实更正。）
-#
-# 为什么用显式签名而非全文数字扫描（据实说明，非偷懒）：
-#   本仓活跃文档中「N 行 / N 条 / N 份」类表述有 49 处（实测：活跃态 21 份文档逐行计），绝大多数是**历史叙述**
-#   （描述某次提交当时的规模，天然不会随当前事实变化）。全文扫描会对这些正确的
-#   历史叙述产生大量假阳性——而 check-loop.mjs 已把「无判定依据的行不产出不可
-#   消除噪声」立为红线（沿 2026-09-27 audit-gate-hardening P3 教训：噪声淹没真漏点）。
-#   故本检查**只校验显式声明的签名**：假阳性恒为 0，代价是覆盖面依赖作者登记。
-#
-# 格式：每行 `<指标名> = <取数表达式>`；`#` 开头为注释；空行忽略。
-# 取数表达式（闭集，全部本地确定性、零网络）：
-#   ledger.lines          台账 .agents/confirmations.jsonl 的非空行数
-#   ledger.linesWithoutBatch   台账中不含 "batch" 字段的行数（schema 演进前历史行）
-#   ledger.linesWithBatch      台账中含 "batch" 字段的行数
-#   docs.count.<sub>      workflow/<sub> 下文档份数——**与文档扫描同口径**：以数字开头的
-#                         .md、排除 _TEMPLATE.md、且仓库模式下只计 HEAD 已跟踪件
-#                         （故并行会话的未跟踪新档不计入）；sub ∈ intents/specs/plans/incidents
-#   docs.count.all        上述四类合计
-# ── 新增指标（2026-09-28 adopter-derivers 起）────────────────────────────────
-# 分两层取数，**内置优先**：
-#   ① 引擎内置 8 个指标（下表）——装户零配置即用，不需要做任何事。
-#   ② 项目自有指标——写 `.agents/metric-derivers.cjs`（**owned**，sync 永不覆盖），
-#      用 CommonJS 导出 `derivers` 对象（指标名 → 取数函数），并在此表加同名一行。
-#      **后缀必须是 `.cjs`、写法必须是 CommonJS**（`module.exports`）。
-#      为什么不用 `.mjs`：引擎用 `require()` 同步载入，而 `require(esm)` 仅在
-#      Node ≥20.19 / ≥22.12 可用——**实测 Node 18.20 / 20.18 / 22.11 全部
-#      ERR_REQUIRE_ESM**，而本仓 engines 声明 `>=18.0.0`。故 `.cjs` 是唯一
-#      全版本可用的形态（同步、零版本依赖）。
-#      旧的 `.mjs` 路径已弃用：若残留在盘上，检查 16 会**明确提示迁移**。
-#
-# 示例 `.agents/metric-derivers.cjs`：
-#     module.exports = {
-#       derivers: {
-#         'my.migrations': (ctx) => ctx.glob('backend/migrations/*.sql').length,
-#         'my.apiCount':   (ctx) => ctx.countFiles('src/api', (f) => f.endsWith('.controller.ts')),
-#       },
-#     };
-# ctx 提供（同步，免你重复造轮子；其余请自行 `require('node:fs')`）：
-#     ctx.root                    仓库根绝对路径
-#     ctx.read(rel)               读文本文件（LF 归一），不存在返回 ''
-#     ctx.glob(pattern)           极简 glob（* / **），返回相对路径数组
-#     ctx.countFiles(dir, pred)   递归计数（可传谓词）
-#
-# 三条硬约定（违反即 fail-loud）：
-#   1. **必须是同步函数**（返回 number，不得 async/Promise）——本检查零网络、要求本地确定性
-#   2. 必须**确定性**：不得依赖网络、不得依赖当前时间
-#   3. 返回值须为**有限数字**（Number.isFinite）
-#
-# 失败语义（**绝不静默降级**）：模块语法错 / 抛异常 / 未导出 derivers / 返回值非法
-#   → 一律出 `[WARN 装户取数器载入失败]` 或 `[WARN 指标取数失败]`，**不会**退化成
-#   「只用内置指标」——否则你会误以为「忘了登记」而查不到真因。
-# 指标名与内置同名时：**内置优先**，你的定义被忽略（会出 advisory 明示）。
-#
-# 注：本检查**不设取数超时**——请让取数器保持轻量（秒级）。死循环会拖慢门禁。
-# 另：装户模块的「取数器」在引擎侧（check-loop.mjs，managed）；本表与 derivers.cjs 同归 owned。
-#
-# 注意：不登记 advisory 总数类指标——它由 check-loop 自身产出（检查 16 是其一部分），
-# 自引用会让「报告本身改变被报告的数」，产生不可稳定对账的循环。
-
-ledger.lines = ledger.lines
-ledger.linesWithoutBatch = ledger.linesWithoutBatch
-ledger.linesWithBatch = ledger.linesWithBatch
-docs.count.intents = docs.count.intents
-docs.count.specs = docs.count.specs
-docs.count.plans = docs.count.plans
-docs.count.incidents = docs.count.incidents
-docs.count.all = docs.count.all