agentic-flow-kit 0.9.0 → 0.9.4

package/templates/_agents/scripts/trust-mode.test.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// trust-mode.test.mjs — AI 自治信任等级 fixture 套件（2026-10-01 gate-script-test-coverage）
+// 覆盖：三级语义（Strict/Standard/Trusted 名称↔数值双轨）、缺文件 fail-closed 回落 Strict、
+// --enable/--disable/--status CLI 行为、非法 --level 拒绝、与 confirm-doc --auto 的端到端
+// （Strict 缺文件拒绝不落账 / Trusted 放行 source=ai-auto-trust-L2）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const TRUST = path.join(SCRIPT_DIR, 'trust-mode.mjs');
+const CONFIRM = path.join(SCRIPT_DIR, 'confirm-doc.mjs');
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+
+const mkfix = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'trust-test-'));
+  for (const s of ['intents', 'plans', 'specs', 'incidents']) {
+    fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
+  }
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.mkdirSync(path.join(d, '.zcode'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-enums.txt'),
+    ['doc.status.all=draft approved done superseded cancelled', 'doc.status.confirmed=approved done superseded cancelled',
+      'doc.status.active=draft approved', 'doc.status.terminal=done superseded cancelled', 'doc.status.abandoned=superseded cancelled',
+      'incident.status.all=open fixed closed', 'incident.status.active=open', 'level.all=L0 L1 L2 L3'].join('\n') + '\n');
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-modules.txt'), '# modules\npipeline\nui\n');
+  return d;
+};
+const runTrust = (root, args) => {
+  const r = spawnSync(process.execPath, [TRUST, ...args], { cwd: root, encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+const cfg = (root) => {
+  const p = path.join(root, '.agents', 'trust-mode.json');
+  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null;
+};
+const ledgerLines = (root) => {
+  const p = path.join(root, '.agents', 'confirmations.jsonl');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8').split(/\n/).filter(Boolean) : [];
+};
+const DRAFT = (level = 'L1') => `---\n状态: draft\n级别: ${level}\nrisk_level: ${level}\n日期: 2026-10-01\n模块: pipeline\n---\n# INTENT — demo\n`;
+
+// T1：缺文件 → fail-closed Strict 默认
+{
+  const d = mkfix();
+  const r = runTrust(d, ['--status']);
+  check('T1 缺文件 --status 输出 Strict/level0/enabled false', r.code === 0 && r.out.includes('"name": "Strict"') && r.out.includes('"level": 0') && r.out.includes('"enabled": false'), r.out);
+}
+// T2：三级语义映射正确
+{
+  check('T2 名称↔数值双轨（NAME_BY_LEVEL 内容）',
+    fs.readFileSync(TRUST, 'utf8').includes("NAME_BY_LEVEL = { 0: 'Strict', 1: 'Standard', 2: 'Trusted' }"), '');
+}
+// T3：--enable --level Trusted → 落盘 enabled true/level 2/name Trusted
+{
+  const d = mkfix();
+  const r = runTrust(d, ['--enable', '--level', 'Trusted']);
+  const c = cfg(d);
+  check('T3 --level Trusted 落盘正确', r.code === 0 && c && c.enabled === true && c.level === 2 && c.name === 'Trusted', JSON.stringify(c));
+}
+// T4：--enable --level 0（Strict 数字）→ 关闭
+{
+  const d = mkfix();
+  const r = runTrust(d, ['--enable', '--level', '0']);
+  const c = cfg(d);
+  check('T4 --level 0 → 关闭 Strict', r.code === 0 && c && c.enabled === false && c.level === 0 && c.name === 'Strict', JSON.stringify(c));
+}
+// T5：非法 --level → 拒绝 exit 1
+{
+  const d = mkfix();
+  const r = runTrust(d, ['--enable', '--level', 'Bogus']);
+  check('T5 非法 --level 拒绝 exit 1', r.code === 1 && r.out.includes('必须为'), r.out);
+}
+// T6：--disable → 关闭 Strict
+{
+  const d = mkfix();
+  runTrust(d, ['--enable', '--level', 'Trusted']);
+  const r = runTrust(d, ['--disable']);
+  const c = cfg(d);
+  check('T6 --disable 复位 Strict', r.code === 0 && c && c.enabled === false && c.level === 0 && c.name === 'Strict', JSON.stringify(c));
+}
+// T7 e2e：Strict（缺文件）下 confirm-doc --auto 拒绝不落账
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, 'workflow', 'intents', '2026-10-01-demo.md'), DRAFT('L1'));
+  const r = spawnSync(process.execPath, [CONFIRM, 'workflow/intents/2026-10-01-demo.md', '--root', d, '--auto'], { cwd: d, encoding: 'utf8' });
+  check('T7 Strict 下 --auto 拒绝且零台账', r.status !== 0 && ledgerLines(d).length === 0, `${r.stdout}${r.stderr}\n${ledgerLines(d).join('|')}`);
+}
+// T8 e2e：Trusted 下 confirm-doc --auto 放行 L1，台账 source=ai-auto-trust-L2
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, 'workflow', 'intents', '2026-10-01-demo.md'), DRAFT('L1'));
+  runTrust(d, ['--enable', '--level', 'Trusted']);
+  const r = spawnSync(process.execPath, [CONFIRM, 'workflow/intents/2026-10-01-demo.md', '--root', d, '--auto'], { cwd: d, encoding: 'utf8' });
+  const lines = ledgerLines(d);
+  check('T8 Trusted 下 --auto 放行并记 ai-auto-trust-L2',
+    r.status === 0 && lines.length === 1 && lines[0].includes('ai-auto-trust-L2') && lines[0].includes('"stage":"approved"'),
+    `${r.stdout}${r.stderr}\n${lines.join('|')}`);
+}
+
+console.log(`\n${fail ? `❌ ${fail} failed` : '✅ all passed'}（${pass} passed）`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts-test-exempt.txt

@@ -0,0 +1,10 @@
+# 引擎脚本测试覆盖豁免登记（单源：本文件——check-loop 检查 20 共读，经 sync 下发装副本）
+# 格式：<脚本名> | <豁免理由> | <覆盖证据（套件名；无自动化覆盖如实写「无」）>
+# 语义：登记 ≠ 免责——须写明理由与覆盖证据；无覆盖的登记是「工具/启动器豁免」，后续批次评估补测。
+# 新增引擎脚本默认必须带同名 .test.mjs（README 规范条目）；确属库件/工具才登记本文件。
+check-metric-claims.mjs | 经 check-loop.mjs 消费 | 由 check-loop.test.mjs 间接覆盖其调用路径
+ensure-board.mjs | 看板启动器（需真实端口/进程环境） | 无（工具豁免，后续批次评估补测）
+policy.mjs | 库件 | 被 check-loop.test.mjs 直接 import 覆盖
+stage-gates.mjs | 库件 | 被 check-loop.test.mjs 直接 import 覆盖（fill-*/confirm-doc.test 消费其行为）
+verify-wiki-consistency.mjs | wiki 一致性校验工具 | 无（工具豁免，后续批次评估补测）
+wiki-search.mjs | 检索库件 | 无（工具豁免，后续批次评估补测）

package/templates/_githooks/pre-commit

@@ -93,6 +93,18 @@ if [ -d templates/_agents ] && [ -f .agents/scripts/check-ledger.mjs ]; then
   fi
 fi
 
+# 确认台账不变量前置（--staged，2026-10-02 ledger-ci-invariant）：暂存的 confirmations.jsonl 必须
+# 是 HEAD 的逐字节前缀扩展（append-only）——本地提交时刻即拦「顺手重写台账」，CI 历史全扫兜底。
+# guard 旧装副本自然跳过；暂存未触台账静默。
+if [ -f .agents/scripts/check-ledger-invariant.mjs ] && command -v node >/dev/null 2>&1; then
+  if git -c core.quotepath=off diff --cached --name-only | grep -q '^\.agents/confirmations\.jsonl$'; then
+    if ! node .agents/scripts/check-ledger-invariant.mjs --staged; then
+      echo "pre-commit: 确认台账不变量未通过，提交已阻止——历史行禁删改（append-only），修正走追加补偿行" >&2
+      exit 1
+    fi
+  fi
+fi
+
 # 项目门禁挂载点：.agents/hooks/local-pre-commit（项目自建门禁/门禁模块接线处，存在即执行）
 if [ -f .agents/hooks/local-pre-commit ]; then
   run_gate "项目门禁（local-pre-commit）" .agents/hooks/local-pre-commit

package/templates/_githooks/pre-push

@@ -5,9 +5,10 @@
 #   - 警告（advisory）= 状态未确认 / 模板占位残留 / 引用漂移 等卫生项 → 仅打印提示
 # stdin 有行时，每个非删除的本地 sha 用 --rev 扫那棵树。没有行时（手跑钩子）仍无参数扫工作区。
 #
-# experiment/* 泳道分支（2026-09-30 hybrid-governance-explore-hardening）：check-loop 降级 advisory——
-#   快速 PoC 推送不因闭环断档被拦（断档报告照出）；转正（合入 main）由下方加固门兜底。
-# 加固门（同日）：推送目标为 refs/heads/main 时以 --hardening 运行——exploring 任务须先收口
+# 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。
 #
@@ -34,33 +35,36 @@ run_loop() {
 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
-  # experiment/* 泳道：advisory（报告不阻断； detached / 其他分支不受影响）
-  case "$local_ref" in
-    refs/heads/experiment/*|experiment/*)
-      echo "pre-push: experiment/* 泳道分支（$local_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
-      continue
-      ;;
-  esac
-  # 加固门：推 main 时追加 --hardening（其余目标维持既有全量扫描）
-  hard_args=""
-  case "$remote_ref" in
-    refs/heads/main|main) hard_args="--hardening" ;;
-  esac
-  run_loop --rev "$local_sha" $hard_args
-  one=$?
-  if [ "$one" -ne 0 ] && [ "$rc" -eq 0 ]; then
-    rc=$one
-  fi
+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" -eq 0 ]; then

package/templates/workflow/README.md

@@ -50,11 +50,12 @@
 
 1. **同名配对**：L1 有 plan；L2/L3 有 spec 与 plan。incident 的回路断档同样阻断。
 2. **验收勾验**：新建 intent 关到 done 时，验收标准未勾则阻断。
-3. **确认留痕**：approved / done / fixed / closed 须经 `confirm-doc.mjs`，指纹与台账一致。
+3. **确认留痕**：approved / done / fixed / closed 须经 `confirm-doc.mjs`，指纹与台账一致。`--delegated` 原话仅限用户对话内明确确认的当次措辞——官方脚本/门禁不得自动代录或编造 quote（2026-10-01 v09-review-defects：solidify-task 曾自动伪造原话，已修复并纳入回归）。
 4. **敏感信息**：pre-commit 的 commit-check 扫描密钥。
 5. **双源与台账**：doctor 核对 managed / owned 的 sha；引擎改动改包源 `templates/` 再 `sync`。
+6. **台账不可变**（2026-10-02 ledger-ci-invariant）：`confirmations.jsonl` 历史行禁删改（append-only 前缀不变量，机器门 = CI 历史全扫 + pre-commit `--staged` 前置）；误写/修正只能**追加补偿行**，篡改历史属审计事件（`git revert` 整个提交后重新追加）。
 
-其余检查（占位符、引用、模块字段、常驻面预算、量化签名、阶段索引、适配器断线）只在 `audit` 不是 `false` 时出警告。
+其余检查（占位符、引用、模块字段、常驻面预算、量化签名、阶段索引、适配器断线、引擎脚本测试覆盖（检查 20，包源环境——新增引擎脚本默认必须带 `.test.mjs`，库件/工具须登记 `.agents/scripts-test-exempt.txt`，2026-10-01 gate-script-test-coverage））只在 `audit` 不是 `false` 时出警告。
 
 **发版草稿**：最近一次改动 `package.json` 的 `version` 的那次提交里，当时已经是 draft 或 approved 的 intent、spec、plan，若被扫描的树上仍是 draft 或 approved，则阻断。当时已是 draft 的不看版本锚。当时已是 approved 的，只在发版版本大于 `policy.mjs` 的 `check17UnclosedAfter` 时阻断；版本 1 没有该键。不带 `--rev` 时现在的状态读工作区，带 `--rev` 时读被推送的那棵树。那次提交之后新建的文件不在范围内。状态为 open 的 incident 不在此列。
 
@@ -63,7 +64,7 @@
 ## 闭环规则
 
 1. L1 以上新需求始于已确认的 intent；L1 以上修复始于已确认的 incident 草稿（作为 intent 等价入口）
-2. L2 / L3 变更必须先有与入口文档同名的 spec 确认通过（L3 加新会话独立复核），方可起草 plan；L1 用极简 plan——改动面 + 验证方式两节起步，多文件多步骤再加任务拆解/执行顺序。**逐阶段前置已机器强制**（2026-09-30 stage-gate-machine）：fill-spec / fill-plan / confirm-doc 校验入口与 spec 前置未过即拒；顺序审计 = check-loop 检查 19
+2. L2 / L3 变更必须先有与入口文档同名的 spec 确认通过（L3 加新会话独立复核），方可起草 plan；L1 用 Quick-Plan 极简三节——改动方案 / 约束与风险 / 验证计划起步（fill-plan.mjs 单源），多文件多步骤再加任务拆解/执行顺序。**逐阶段前置已机器强制**（2026-09-30 stage-gate-machine）：fill-spec / fill-plan / confirm-doc 校验入口与 spec 前置未过即拒；顺序审计 = check-loop 检查 19
 3. 实现产物必须通过静态门（构建 + 测试 + 项目门禁）
 4. 线上 / 实测缺陷回落到 `incidents/`，复盘三件套（新 intent、防复发验证、规范条目）缺一不可；**根因属「门禁缺位 / 规范未落地 / 系统性问题」时，即使结构性修复已完成也必须立新 intent** 追踪系统性改进，禁止以「修复已完成」为由绕过 intent 回路
 5. 关单在 test：逐条勾验入口文档「验收标准」并补证据后 intent → done（不依赖是否上 prod）。done 仍有未勾项会被 check-loop 拦（新建 intent hard-block）。上 prod 另走 deploy（tag / 回滚 / 观察）

package/templates/workflow/plans/_TEMPLATE.md

@@ -6,7 +6,7 @@
 # PLAN — <与入口文档同名主题>
 <!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2/L3 必须先有 ../specs/ 同名 spec 确认通过；AI 起草、用户对话内确认后开工 -->
 <!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；正文不再写状态/级别行 -->
-<!-- L1 极简形态（2026-09-13 瘦身，L1 默认）：单/少文件微改动只填「改动面」+「验证方式」两节——改动面逐条列改哪个文件做什么（判据细节直接写进条目），验证一行静态门 + 按需 UI 实测；任务拆解/执行顺序仅 L1 多文件多步骤时保留 -->
+<!-- L1 极简形态（Quick-Plan，与 fill-plan.mjs 单源一致）：单/少文件微改动只填「改动方案」+「约束与风险」+「验证计划」三节——改动方案逐条列改哪个文件做什么（判据细节直接写进条目），验证计划一行静态门 + 按需 UI 实测；任务拆解/执行顺序仅 L1 多文件多步骤时保留 -->
 
 对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）
 对应 spec：../specs/YYYY-MM-DD-<主题>.md（L1 可省略）