agentic-flow-kit 1.8.1 → 1.8.7

package/templates/_githooks/pre-push

@@ -1,82 +1,136 @@
-#!/bin/sh
-# Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发）
-# 跑 .agents/scripts/check-loop.sh：扫 workflow/ 闭环骨架断档（2026-10-13 分道——默认只扫硬门，源仓同款）
-#   - 硬阻断（exit 1）= 配对断裂 / 回路断档 等硬门违例 → push 立即阻断
-#   - 卫生项（索引/宿主/词表/体积预算等 WARN 面）不进 push 门——要看时手跑 check-loop.mjs --hygiene
-#     （--all 两面都跑 = 分道前的裸跑全量）
-# stdin 有行时，每个非删除的本地 sha 用 --rev 扫那棵树。没有行时（手跑钩子）仍无参数扫工作区。
-#
-# experiment/* 泳道（2026-09-30 hybrid-governance-explore-hardening）：**目标分支**为 experiment/* 时，
-#   闭环扫描降级 advisory（报告不阻断）——快速 PoC 推送不因闭环断档被拦；转正（目标为 main）由加固门兜底。
-# 加固门（同日；2026-10-01 v09-review-defects 修正判定键）：推送**目标**为 refs/heads/main 时以
-#   --hardening 运行（无论来源分支——experiment/* 直推 main 同样覆盖），exploring 任务须先收口
-#   （intent approved/done + 同名 plan 在场 + L2/L3 另须同名 spec；判据见 check-loop.mjs 加固门段），
-#   hard 失败即阻断 push，防「未文档化的探索件」进 main。
-#
-# 机器门：本地钩子跑 check-loop.sh。装户仓的远端门是随包下发的 .github/workflows/kit-ci.yml（verify.mjs）。
-# kit 源仓：.github/workflows/ci.yml 于 push main / 全部 PR 跑 npm test（lint + 全量套件）。
-# 装户仓无包源 templates/：sync-hosts 等包源命令不适用。本地钩子仍是提交时刻的机器门。
-# 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
+#!/usr/bin/env node
+// Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发）— agentic-flow-kit 通用编排
+// 2026-10-16 node 化（自源仓 2ff869a9/13f67ef7 回灌 pre-push 面）：钩子体不再含 sh 逻辑——git 仍以自带
+// sh 启动本文件（钩子机制要求），但 shebang 即 node，PATH 无 sh 不影响任何逻辑。写法为 CommonJS——
+// 无扩展名文件 node 缺省按 CJS 解析，不依赖 ≥22.7 的 ESM 语法探测。
+// 跑 .agents/scripts/check-loop.mjs：扫 workflow/ 闭环骨架断档（默认只扫硬门）
+//   - 硬阻断（exit 1）= 配对断裂 / 回路断档 / 证据与确认链 / 发版未收口 → push 立即阻断
+//   - 卫生段（模板占位 / 引用漂移 / 宿主副本 / 索引）不在本钩子。要看时跑 --hygiene 或 --all
+// stdin 有行时，每个非删除的本地 sha 用 --rev 扫那棵树。没有行时（手跑钩子）仍无参数扫工作区。
+//
+// 构建门（2026-10-16 自 pre-commit 后移）：另跑 commit-check.cjs --range <old> <new> 按推送范围条件构建
+// （常规提交时刻只做敏感扫描——提交内环提速；构建执法集中到推送与关单）。范围匹配逻辑单源 =
+// commit-check.cjs。experiment/* 目标降级 advisory。手动运行（无 stdin 推送行）无范围事实，构建门跳过。
+//
+// experiment/* 泳道：**目标分支**为 experiment/* 时，闭环扫描与构建门降级 advisory（报告不阻断）——
+// 快速 PoC 推送不因闭环断档/构建失败被拦；转正（目标为 main）由加固门兜底。
+// 加固门（2026-10-01 v09-review-defects）：推送**目标**为 refs/heads/main 时以 --hardening 运行
+// （无论来源分支——experiment/* 直推 main 同样覆盖），exploring 任务须先收口（intent approved/done +
+// 同名 plan 在场 + L2/L3 另须同名 spec；判据见 check-loop.mjs 加固门段），hard 失败即阻断 push。
+//
+// 回路日检（2026-10-16 自源仓 13f67ef7 回灌）：退役催办与 papercut 报债此前无调度，机制空转。每个
+// 本地日在推送成功路径跑一次，advisory，失败不改退出码。摘要落 .agents/cache/loop-watch.jsonl（gitignore）。
+//
+// 机器门：本地钩子跑 check-loop.mjs。装户仓的远端门是随包下发的 .github/workflows/kit-ci.yml（verify.mjs）。
+// kit 源仓：.github/workflows/ci.yml 于 push main / 全部 PR 跑 npm test（lint + 全量套件）。
+// 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
 
-cd "$(git rev-parse --show-toplevel)" || exit 1
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-push: 无法定位仓库根——推送已阻止');
+  process.exit(1);
+}
+process.chdir(top.stdout.trim());
+
+const LOOP = '.agents/scripts/check-loop.mjs';
+if (!fs.existsSync(LOOP)) {
+  console.error(`pre-push: 未找到 ${LOOP}——闭环扫描无法执行，推送已阻止（脚本随包下发；flow-kit sync 恢复后重试）`);
+  process.exit(1);
+}
+// 构建门脚本（2026-10-16 自 pre-commit 后移）：缺失 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);
+}
 
-SCRIPT=".agents/scripts/check-loop.sh"
-if [ ! -f "$SCRIPT" ]; then
-  echo "pre-push: 未找到 $SCRIPT，跳过闭环扫描" >&2
-  exit 0
-fi
+const runLoop = (args = []) => spawnSync(process.execPath, [LOOP, ...args], { stdio: 'inherit' });
+// 范围参数：远端全零 sha（新分支首推）→ 全量构建语义（commit-check 认全零 old）
+const rangeArgsOf = (remoteSha, localSha) => ['--range', remoteSha && !/^0+$/.test(remoteSha) ? remoteSha : '0'.repeat(40), localSha];
 
-run_loop() {
-  if command -v sh >/dev/null 2>&1; then
-    sh "$SCRIPT" "$@"
-  else
-    bash "$SCRIPT" "$@"
-  fi
+let stdinText = '';
+try { stdinText = fs.readFileSync(0, 'utf8'); } catch { stdinText = ''; }
+
+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）：
+  // main → 加固门（必带 --hardening）；experiment/* → advisory（报告不阻断）；其他 → 全量扫描（硬门）
+  if (/^refs\/heads\/main$|^main$/.test(remoteRef)) {
+    const r = runLoop(['--rev', localSha, '--hardening']);
+    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;
+  } else if (/^refs\/heads\/experiment\/|^experiment\//.test(remoteRef)) {
+    console.error(`pre-push: experiment/* 目标分支（${remoteRef}）——闭环扫描与构建门降级 advisory，不阻断`);
+    const adv = spawnSync(process.execPath, [LOOP, '--rev', localSha], { stdio: 'inherit' });
+    if (adv.status !== 0) console.error('pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送，转正（推 main）须过加固门');
+    const advB = spawnSync(process.execPath, [BUILD_CHECK, ...rangeArgsOf(remoteSha, localSha)], { stdio: 'inherit' });
+    if (advB.status !== 0) console.error('pre-push: （advisory）构建门未过已在上方列出——experiment 泳道不阻断推送');
+  } else {
+    const r = runLoop(['--rev', 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;
+  }
 }
 
-saw=0
-rc=0
-while read -r local_ref local_sha remote_ref _remote_sha; do
-saw=1
-case "$local_sha" in
-*[!0]*) ;;
-*) continue ;;
-esac
-# 按目标分支三态分派（2026-10-01 v09-review-defects：判定键从 local_ref 改为 remote_ref——
-# 修复 experiment/*→main 直推被 advisory continue 吞掉加固门的漏口）：
-#   main            → 加固门（必带 --hardening）
-#   experiment/*    → advisory（报告不阻断）
-#   其他            → 全量扫描
-case "$remote_ref" in
-refs/heads/main|main)
-run_loop --rev "$local_sha" --hardening
-;;
-refs/heads/experiment/*|experiment/*)
-echo "pre-push: experiment/* 目标分支（$remote_ref）——闭环扫描降级 advisory，不阻断" >&2
-if command -v sh >/dev/null 2>&1; then
-sh "$SCRIPT" --rev "$local_sha" >&2 || echo "pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送，转正（推 main）须过加固门" >&2
-else
-bash "$SCRIPT" --rev "$local_sha" >&2 || echo "pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送，转正（推 main）须过加固门" >&2
-fi
-;;
-*)
-run_loop --rev "$local_sha"
-;;
-esac
-one=$?
-if [ "$one" -ne 0 ] && [ "$rc" -eq 0 ]; then
-rc=$one
-fi
-done
+if (saw === 0) {
+  const r = runLoop();
+  if (r.status !== 0) rc = r.status === null ? 1 : r.status;
+  console.error('pre-push: 手动运行无推送范围——构建门跳过（真实推送时按 old..new 范围执法）');
+}
 
-if [ "$saw" -eq 0 ]; then
-  run_loop
-  rc=$?
-fi
+if (rc !== 0) {
+  console.error('pre-push: 闭环骨架断档 / 构建未过（hard-block）未通过，push 已阻断。修 workflow 文档 / 构建错误后重推——不要用 --no-verify 绕过（本钩子是唯一机器门，无服务端兜底，见头部说明）');
+  console.error('pre-push: 若为「加固未过」= experiment 泳道件转正前须收口：intent approved/done + 同名 plan（L2/L3 另须 spec）且状态非 draft');
+  process.exit(rc);
+}
 
-if [ "$rc" -ne 0 ]; then
-  echo "pre-push: 闭环骨架断档（hard-block）未通过，push 已阻断。修 workflow 文档后重推——不要用 --no-verify 绕过（本钩子是唯一机器门，无服务端兜底，见头部说明）" >&2
-  echo "pre-push: 若为「加固未过」= experiment 泳道件转正前须收口：intent approved/done + 同名 plan（L2/L3 另须 spec）且状态非 draft" >&2
-  exit "$rc"
-fi
-exit 0
+// 回路日检（2026-10-16 自源仓 13f67ef7 回灌）：每个本地日在推送成功路径跑一次，advisory，失败不改退出码。
+try {
+  const cacheDir = '.agents/cache';
+  const stampPath = `${cacheDir}/loop-watch-stamp`;
+  const ledgerPath = `${cacheDir}/loop-watch.jsonl`;
+  const now = new Date();
+  const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+  let prev = '';
+  try { prev = fs.readFileSync(stampPath, 'utf8').trim(); } catch { /* 首跑 */ }
+  if (prev !== today) {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // 退役催办：mechanism-retire-watch（--json 产 actions）；papercut 报债：kit 复用 sensor --json 取 debt
+    const jobs = [
+      ['retire-watch', '.agents/scripts/mechanism-retire-watch.mjs'],
+      ['papercut-report', '.agents/scripts/papercut-debt-sensor.mjs'],
+    ];
+    const runs = [];
+    for (const [id, script] of jobs) {
+      if (!fs.existsSync(script)) { runs.push({ id, missing: true }); continue; }
+      const r = spawnSync(process.execPath, [script, '--json'], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+      let summary = {};
+      try { summary = JSON.parse(r.stdout || '{}'); } catch { summary = { parseError: true }; }
+      runs.push({
+        id,
+        exit: r.status,
+        actions: Array.isArray(summary.actions) ? summary.actions.length : null,
+        debt: typeof summary.debt === 'number' ? summary.debt : null,
+      });
+    }
+    fs.appendFileSync(ledgerPath, `${JSON.stringify({ ts: now.toISOString(), day: today, runs })}\n`);
+    fs.writeFileSync(stampPath, `${today}\n`);
+    const retire = runs.find((x) => x.id === 'retire-watch');
+    const paper = runs.find((x) => x.id === 'papercut-report');
+    console.error(`pre-push: （advisory）回路日检已记 ${ledgerPath}（退役动作 ${retire && retire.actions != null ? retire.actions : '?'}，papercut debt ${paper && paper.debt != null ? paper.debt : '?'}）`);
+  }
+} catch (e) {
+  console.error(`pre-push: （advisory）回路日检跳过——${e.message}`);
+}
+process.exit(0);

package/templates/workflow/README.md

@@ -32,8 +32,9 @@
 - **验证**：`.agents/commands/test.md`（静态门 + 实测；项目自有验证脚本/门禁如有，见 `.agents/hooks/local-pre-commit` 与根 `AGENTS.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）
+- **量化**：委派/自做结果记 `delegations.md`，聚合跑 `node .agents/scripts/agg-delegations.cjs`（**并发扩容门槛见该文件——数字达标前不扩并发**）；语料与常驻面体积的**月度快照**跑 `node .agents/scripts/gen-workflow-metrics.mjs`（每月一行落 `metrics.md`，同月重跑即更新；明细看 stdout）；独立复核的**意见级处置**记 `workflow/reviews.d/<YYYY-MM>.md`（一行 = 一次复核事件，八列 `日期|对象|复核员|意见数|采纳|拒绝|误报|备注`，采纳+拒绝+误报=意见数，月度聚合进 metrics「复核效果」表——口径详见 `.agents/commands/review.md` 落账子项）
 - **归档**：终态件滚动归档跑 `node .agents/scripts/archive-sweep.mjs`（缺省 dry-run 预览；`--window 21 --execute` 执行 git mv）——归档单位 = **同名家族**（intent/spec/plan/incident 同进同退：任一成员非终态 / 未满窗 / 被活跃引用 / 无日期，整族留守）；终态时间三级锚 = 确认台账终态行 ts → 内容 last-touch（frontmatter-only 提交不刷新）→ 文件名日期；落点 `workflow/archive/<家族最晚终态月>/<类型>/`
+- **spec 生命周期口径（spec-anchored + 长期维护）**：spec 是**持续对照的事实源，交付后不失效**——代码改动触及某 spec 覆盖的行为时须对照该 spec（含归档件）：行为漂移要么改代码回到 spec，要么同一提交回改 spec；有争议立 incident 裁决。**归档是容量治理不是失效**：归档只把终态件移出活跃扫描面（INDEX 活跃行 / check-loop 四目录扫描 / 月度快照采集），事实源地位与修订权不变——归档 spec 可原地修订，修订不改归档位置。体积治理先观察后设限：spec 行数/验收条数分布由 `gen-workflow-metrics.mjs` 的「spec 体积观察」表采集（advisory 上限显式延后，先让体积可见）
 - **papercut 回路（存量债清偿，手动触发）**：命令/技能卡壳记 `workflow/papercuts.md` 攒成的未升级条目 = 存量债；要清时跑 `node .agents/scripts/papercut-debt-sensor.mjs`（测 debt）→ `node .agents/scripts/papercut-debt-controller.mjs`（确定性选本轮唯一目标；源码/数据库面条目被 scope gate 拦下等授权）→ 按 `.agents/skills/papercut-fix/SKILL.md` 执行（改完 debt 应恰好 -1）。判定与排序口径单源 `.agents/loop/papercut-debt/DESIGN.md`，改口径先改设计文件
 - **追溯**：git 即审计——文档随代码同 commit、上线打 `release/<日期>` tag，`git log` 全链路可查；多人评审暂缓，git 历史即评审记录
 - **级别**：L1 实现级（未命中 L2/L3；新需求的入口是 plan）｜ L2 规则 / 契约（编码权威 / 共享契约 / 既有接口语义 / 全局横切口径，触达面闭集见 `.agents/commands/new-task.md` §级别判断）｜ L3 数据与运行时结构（schema / 迁移 SQL / DI 链 / 认证与中间件管线）；混合改动就高不就低

package/templates/workflow/intents/_TEMPLATE.md

@@ -12,6 +12,11 @@
 <!-- frontmatter 受限子集（2026-09-13）：每行 `键: 值`；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L1/L2/L3；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->
 <!-- 探索泳道（可选，2026-09-30 hybrid-governance-explore-hardening）：experiment/ 前缀分支上的 PoC 任务在 frontmatter 加「阶段: exploring」——提交/推送门降级 advisory，spec/plan 可先于本入口确认起草（限 L1）；转正合入 main 前须收口（本档 approved/done + 同名 plan/spec 在场，check-loop --hardening 加固门），或显式放弃（superseded/cancelled） -->
 <!-- 预判（可选，2026-10-13 自 Shipyard 回灌 prejudgment-ledger）：定级时先做结构化预判，结果如实写「预判: kind=<require|fix|verify|review|deploy> level=<L1|L2|L3>」——intents≡require、incidents≡fix；与实际落位不符时 check-loop 路由预判一致性检查（B6b 落地后编号以 check-loop.mjs 头部清单为准）出 WARN 留账。缺字段零告警（存量宽容不回填，不做强制前置）——advisory 灰度口径 -->
+<!-- 待澄清标记（2026-10-12 needs-clarification；2026-10-18 立项跳对称化扩到本模板）：起草时
+     不确定的地方照实写一行 `- 待澄清：<你卡在哪>`，不要猜一个填上去——立项是后链全部文档的种子，
+     「我不知道」是负责，猜是失职。起草门不拦（不阻塞继续写）；但 draft→approved 确认时仍挂着
+     未澄清项会被 confirm-doc 拒绝落账。解决后把行首改成 `- 已澄清：…`（保留该行留痕）或直接删行。
+     判据单源：stage-gates.mjs#openClarifications / clarifyGateFor。存量 intent 无标记零回溯。 -->
 
 ## 背景与问题
 <为什么做；写明需求来源（工单 / 沟通记录 / 待办事项）>

package/templates/workflow/specs/_TEMPLATE.md

@@ -44,7 +44,7 @@ THEN 行是机器对账断言：声明了场景却缺「- THEN <可观测结果>
 - 前端：路由 / 组件 / store / api
 
 ## 约束遵守映射（对照 AGENTS.md 触达红线）
-| 红线（按本项目 AGENTS.md 实际红线逐行填，没有的行删除） | 本 spec 如何满足 |
+| 红线 / 工程原则（按本项目 AGENTS.md 红线与「工程原则」节实际行逐行填，没有的行删除） | 本 spec 如何满足 |
 |------|------------------|
 | <示例：分层依赖约束 / 编码权威归属 / 数据迁移方式> | <通过 XXX，不引入 YYY；是否触及（触及即 L2 定级依据）> |
 | <示例：schema / 迁移路径约束> | <涉及路径与处理方式> |