agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/scripts/ci-push-before.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// 在 Azure Pipelines 上解析本次构建关联提交里最老一笔的第一父，
+// 用 logging command 写入 CI_PUSH_BEFORE，供 check-lane-surface --ci 做整段 push diff。
+// 任何失败都 exit 0：缺令牌、HTTP 非 200、空列表、第一父不是 sha → stderr advisory，
+// 泳道门退回 HEAD~1。不在这里访问网络以外的副作用。
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { ciPushBefore } from './check-lane-surface.mjs';
+
+const advisory = (msg) => {
+  console.error(`ci-push-before: advisory: ${msg}——泳道 CI 退回 HEAD~1`);
+};
+
+const argOf = (k) => {
+  const i = process.argv.indexOf(k);
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : '';
+};
+
+const loadChanges = async () => {
+  const file = argOf('--changes-file');
+  if (file) return JSON.parse(fs.readFileSync(file, 'utf8'));
+  const token = process.env.SYSTEM_ACCESSTOKEN || '';
+  const collection = process.env.SYSTEM_COLLECTIONURI || '';
+  const project = process.env.SYSTEM_TEAMPROJECT || '';
+  const buildId = process.env.BUILD_BUILDID || '';
+  if (!token || !collection || !project || !buildId) {
+    advisory('缺少 SYSTEM_ACCESSTOKEN / SYSTEM_COLLECTIONURI / SYSTEM_TEAMPROJECT / BUILD_BUILDID');
+    return null;
+  }
+  const url = `${collection.replace(/\/?$/, '/')}${encodeURIComponent(project)}/_apis/build/builds/${encodeURIComponent(buildId)}/changes?api-version=7.1`;
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+  if (!res.ok) {
+    advisory(`changes API HTTP ${res.status}`);
+    return null;
+  }
+  return res.json();
+};
+
+const changes = await loadChanges();
+if (changes) {
+  const parentOf = (id) => {
+    const r = spawnSync('git', ['rev-parse', `${id}^`], { encoding: 'utf8' });
+    return r.status === 0 ? String(r.stdout || '').trim() : '';
+  };
+  const { before, reason } = ciPushBefore(changes, parentOf);
+  if (!before) advisory(reason);
+  else console.log(`##vso[task.setvariable variable=CI_PUSH_BEFORE]${before}`);
+}
+process.exit(0);

package/templates/engine/.agents/scripts/claims.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// claims.mjs — 主张账（workflow/claims.d/<YYYY-MM>.jsonl）
+// 一条主张 = 未来会话可能当真的一句话 + 仓库里已经存在的原文片段。
+// 脚本只回答原文还在不在：held = quote 仍在文件中，broken = 文件消失或 quote 已不在。
+// 原文还在不等于主张为真。核对只报告，退出码恒 0，不改正文、不改历史行。
+//
+// 用法：
+//   node .agents/scripts/claims.mjs add --claim "..." --path <相对路径> --quote "..."
+//   node .agents/scripts/claims.mjs recheck
+// 库：addClaim({ root, claim, path, quote, now }) / recheckClaims(root)
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const QUOTE_MIN = 8;
+const QUOTE_MAX = 200;
+const CLAIM_MAX = 400;
+
+export function addClaim({ root, claim, path: rel, quote, now = new Date() }) {
+  const text = requireClaim(claim);
+  const snippet = requireQuote(quote);
+  const target = resolveRel(root, rel);
+  const body = readNorm(target.abs);
+  if (!body.includes(norm(snippet))) {
+    throw new Error('quote 不在文件中，拒绝写入');
+  }
+  const row = {
+    ts: now.toISOString(),
+    id: `c-${crypto.randomBytes(4).toString('hex')}`,
+    claim: text,
+    path: target.rel,
+    quote: snippet,
+  };
+  const dir = path.join(path.resolve(root), 'workflow', 'claims.d');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${row.ts.slice(0, 7)}.jsonl`);
+  fs.appendFileSync(file, `${JSON.stringify(row)}\n`);
+  return row;
+}
+
+export function recheckClaims(root) {
+  const dir = path.join(path.resolve(root), 'workflow', 'claims.d');
+  const results = [];
+  if (!fs.existsSync(dir)) return { held: 0, broken: 0, results };
+  const files = fs.readdirSync(dir).filter((n) => /^\d{4}-\d{2}\.jsonl$/.test(n)).sort();
+  for (const name of files) {
+    const raw = fs.readFileSync(path.join(dir, name), 'utf8');
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      results.push(checkLine(root, line));
+    }
+  }
+  const held = results.filter((r) => r.status === 'held').length;
+  return { held, broken: results.length - held, results };
+}
+
+function checkLine(root, line) {
+  let row;
+  try {
+    row = JSON.parse(line);
+  } catch {
+    return { id: '(malformed)', path: '', claim: '', status: 'broken', reason: 'malformed' };
+  }
+  const id = typeof row.id === 'string' ? row.id : '(malformed)';
+  const claim = typeof row.claim === 'string' ? row.claim : '';
+  const rel = typeof row.path === 'string' ? row.path : '';
+  const quote = typeof row.quote === 'string' ? row.quote : '';
+  if (!rel || !quote) {
+    return { id, path: rel, claim, status: 'broken', reason: 'malformed' };
+  }
+  let abs;
+  try {
+    abs = resolveRel(root, rel).abs;
+  } catch {
+    return { id, path: rel, claim, status: 'broken', reason: 'file-missing' };
+  }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    return { id, path: rel, claim, status: 'broken', reason: 'file-missing' };
+  }
+  if (!readNorm(abs).includes(norm(quote))) {
+    return { id, path: rel, claim, status: 'broken', reason: 'quote-missing' };
+  }
+  return { id, path: rel, claim, status: 'held', reason: 'quote-present' };
+}
+
+function requireClaim(claim) {
+  if (typeof claim !== 'string' || claim.trim() === '' || Array.from(claim).length > CLAIM_MAX) {
+    throw new Error('claim 须为一句非空文本（不超过 400 字）');
+  }
+  return claim;
+}
+
+function requireQuote(quote) {
+  if (typeof quote !== 'string') throw new Error(`quote 须为 ${QUOTE_MIN} 到 ${QUOTE_MAX} 字`);
+  const n = Array.from(quote).length;
+  if (n < QUOTE_MIN || n > QUOTE_MAX) {
+    throw new Error(`quote 须为 ${QUOTE_MIN} 到 ${QUOTE_MAX} 字`);
+  }
+  return quote;
+}
+
+function resolveRel(root, rel) {
+  if (typeof rel !== 'string' || rel === '' || path.isAbsolute(rel)) {
+    throw new Error('path 须为相对路径');
+  }
+  const posix = rel.replace(/\\/g, '/');
+  if (posix.split('/').includes('..')) throw new Error('path 禁止 ..');
+  const lower = posix.toLowerCase();
+  if (lower === 'tmp' || lower.startsWith('tmp/') || lower === '.agents/cache' || lower.startsWith('.agents/cache/')) {
+    throw new Error('path 禁止落在 tmp/ 或 .agents/cache/');
+  }
+  const rootAbs = path.resolve(root);
+  const abs = path.resolve(rootAbs, rel);
+  const back = path.relative(rootAbs, abs);
+  if (back.startsWith('..') || path.isAbsolute(back)) throw new Error('path 须留在仓库内');
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error('path 不是已存在的文件');
+  return { abs, rel: posix };
+}
+
+function norm(s) {
+  return s.replace(/\r\n/g, '\n');
+}
+
+function readNorm(abs) {
+  return norm(fs.readFileSync(abs, 'utf8'));
+}
+
+function arg(name) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+
+function main() {
+  const root = arg('--root') || process.env.CHECK_LOOP_ROOT || process.cwd();
+  const cmd = process.argv[2];
+  try {
+    if (cmd === 'add') {
+      const row = addClaim({
+        root,
+        claim: arg('--claim'),
+        path: arg('--path'),
+        quote: arg('--quote'),
+      });
+      console.log(row.id);
+      return;
+    }
+    if (cmd === 'recheck') {
+      const report = recheckClaims(root);
+      console.log(`held ${report.held}`);
+      console.log(`broken ${report.broken}`);
+      for (const row of report.results) {
+        if (row.status === 'broken') console.log(`broken ${row.id} ${row.path}: ${row.reason}`);
+      }
+      return;
+    }
+    console.error('用法: claims.mjs add --claim --path --quote | claims.mjs recheck');
+    process.exit(2);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(2);
+  }
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (isMain) main();

package/templates/engine/.agents/scripts/closeout.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// closeout.mjs — 关单序列串接（closeout-skill-hardening 2026-11-08）
+// 把 .agents/skills/shipyard-workflow-closeout/SKILL.md §3–§5 的固定三步收成一次调用：
+//   ① confirm-doc 落终态 → ② gen-workflow-index 重生成 → ③ git add 固定路径清单 → ④ commit。
+// 动机：三步顺序与路径清单每次相同，手工逐条跑时漏 add 分片 / 夹带无关文件是高发段；收成入口后
+// 技能正文从操作手册缩成调用 + 判据。提交一律不用 --no-verify（钩子照常跑）。
+// 幂等 / 恢复：任一步失败即停并报「从哪一步重入」；重跑时已到终态（done/closed/cancelled/superseded）
+// 的文档跳过 confirm，index 生成器幂等，无暂存改动则跳过 commit。
+// 安全边界：commit 前核对暂存区只有候选路径——存在外来暂存路径即拒绝提交，不夹带用户其它在途改动。
+// 用法：node .agents/scripts/closeout.mjs <workflow/.../x.md> --delegated "<用户对话原话>"
+//         [--msg "<提交主题>"] [--root <仓库根>] [--dry-run]
+//   --dry-run 只报告当前状态 / 下一跳 / 候选路径变更，不落态、不写盘、不提交。
+import fs from 'node:fs';
+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 argv = process.argv.slice(2);
+const argOf = (k) => { const i = argv.indexOf(k); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : ''; };
+let quote = null;
+let msg = null;
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--delegated') { quote = argv[++i] ?? ''; continue; }
+  if (argv[i] === '--msg') { msg = argv[++i] ?? ''; continue; }
+  if (argv[i] === '--root') { i++; continue; }
+  if (argv[i] === '--dry-run') continue;
+  positional.push(argv[i]);
+}
+const DRY = argv.includes('--dry-run');
+const ROOT = path.resolve(argOf('--root') || path.join(SCRIPT_DIR, '..', '..'));
+
+const USAGE = '用法：node .agents/scripts/closeout.mjs <workflow/{intents,specs,plans,incidents}/x.md> --delegated "<用户原话>" [--msg "<主题>"] [--root <仓库根>] [--dry-run]';
+const RECOVER = (doc) => `恢复：修掉报错原因后重跑同一命令（已完成的步骤幂等跳过）：node .agents/scripts/closeout.mjs ${doc} --delegated "<用户原话>" [--msg "<主题>"]`;
+if (positional.length !== 1) { console.error(`❌ 需且仅需一份文档\n${USAGE}`); process.exit(1); }
+const doc = positional[0].replace(/\\/g, '/');
+if (!/^workflow\/(intents|specs|plans|incidents)\/[^/\\]+\.md$/.test(doc)) {
+  console.error(`❌ 文档路径不合法：${doc}\n${USAGE}`); process.exit(1);
+}
+const abs = path.join(ROOT, doc);
+if (!fs.existsSync(abs)) { console.error(`❌ 文档不存在：${abs}`); process.exit(1); }
+
+const base = path.basename(doc, '.md');
+const candidates = [
+  doc,
+  'workflow/INDEX.md',
+  'workflow/verify-evidence.md',
+  `.agents/confirmations.d/${base}.jsonl`,
+  '.agents/confirmations.jsonl',
+];
+const TERMINAL = ['done', 'closed', 'cancelled', 'superseded'];
+function statusOf() {
+  const nl = fs.readFileSync(abs, 'utf8').split(/\r?\n/);
+  if (!/^---\s*$/.test(nl[0] || '')) return '';
+  for (let i = 1; i < nl.length && !/^---\s*$/.test(nl[i]); i++) {
+    const m = nl[i].match(/^状态:\s*(.*)$/);
+    if (m) return m[1].trim();
+  }
+  return '';
+}
+function git(args) {
+  return spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+}
+function porcelain(args) {
+  const r = git(args);
+  if (r.status !== 0) return [];
+  return String(r.stdout || '').split(/\r?\n/)
+    .map((l) => l.slice(3).split(' -> ').pop().trim().replace(/^"|"$/g, '').replace(/\\/g, '/'))
+    .filter(Boolean);
+}
+// git diff --name-only 输出是纯路径（无 XY 前缀），不能走 porcelain 的 slice(3)。
+function nameOnly(args) {
+  const r = git(args);
+  if (r.status !== 0) return [];
+  return String(r.stdout || '').split(/\r?\n/)
+    .map((l) => l.trim().replace(/^"|"$/g, '').replace(/\\/g, '/'))
+    .filter(Boolean);
+}
+function run(label, args, opts = {}) {
+  const r = spawnSync(opts.cmd || process.execPath, args, { cwd: ROOT, encoding: 'utf8' });
+  const out = `${r.stdout || ''}${r.stderr || ''}`.trim();
+  if (r.status !== 0) {
+    console.error(`❌ 步骤 ${label} 失败（exit ${r.status}）:\n${out}`);
+    console.error(RECOVER(doc));
+    process.exit(r.status || 1);
+  }
+  if (out) console.log(out);
+}
+const st = statusOf();
+const terminal = TERMINAL.includes(st);
+console.log(`[closeout] ${doc}：当前状态 ${st || '缺失'}${terminal ? '（终态，跳过代录）' : '（待代录）'}`);
+if (DRY) {
+  console.log('[closeout] --dry-run：不落态、不写盘、不提交');
+  console.log(`[closeout] 候选路径变更：${porcelain(['status', '--porcelain', '--', ...candidates]).join('、') || '(无)'}`);
+  console.log(`[closeout] 暂存区路径：${nameOnly(['diff', '--cached', '--name-only']).join('、') || '(无)'}`);
+  process.exit(0);
+}
+// ① 代录终态（状态行只由 confirm-doc.mjs 改；incident 两跳各跑一次本脚本）
+if (!terminal) {
+  if (quote === null) { console.error(`❌ 代录须 --delegated "<用户对话原话>"\n${USAGE}`); process.exit(1); }
+  run('① confirm-doc', [path.join(SCRIPT_DIR, 'confirm-doc.mjs'), doc, '--delegated', quote, '--root', ROOT]);
+} else {
+  console.log('[closeout] ① 已是终态，跳过 confirm-doc（幂等重入）');
+}
+// ② 索引（生成器按磁盘重写 GENERATED 区，幂等）
+run('② gen-workflow-index', [path.join(SCRIPT_DIR, 'gen-workflow-index.mjs')]);
+// ③ git add 固定路径清单（只 add 有变更的候选）
+const changed = porcelain(['status', '--porcelain', '--', ...candidates]);
+if (changed.length) run('③ git add', ['add', '--', ...changed], { cmd: 'git' });
+else console.log('[closeout] ③ 候选路径无变更，跳过 git add');
+// 提交前安全边界：暂存区若有候选清单之外的路径，拒绝提交（用户其它在途改动须自己提交）
+const staged = nameOnly(['diff', '--cached', '--name-only']);
+const foreign = staged.filter((p) => !candidates.includes(p));
+if (foreign.length) {
+  console.error(`❌ 步骤 ④ 拒绝提交：暂存区有本序列之外的路径（${foreign.slice(0, 5).join('、')}${foreign.length > 5 ? '…' : ''}）——不夹带其它在途改动`);
+  console.error(`   先单独提交或撤销这些路径，再重跑（本次已落态与索引，重跑幂等跳过）\n${RECOVER(doc)}`);
+  process.exit(1);
+}
+if (!staged.length) {
+  console.log('[closeout] ④ 暂存区无改动（可能已提交），跳过 commit——关单完成');
+  process.exit(0);
+}
+console.log(`[closeout] 待提交：${staged.join('、')}`);
+const subject = msg || `docs(workflow): ${base} 关单`;
+run('④ git commit', ['commit', '-m', subject], { cmd: 'git' });
+console.log(`[closeout] ✅ 关单提交完成：${subject}`);

package/templates/engine/.agents/scripts/compact-ledgers.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// compact-ledgers.mjs — 台账分片打包归并器（2026-10-10 中期方案配套工具）
+// 用途：在里程碑节点或发布前，可选运行本脚本将 .agents/confirmations.d/*.jsonl
+// 中的分片确认行安全合并回归档主台账 .agents/confirmations.jsonl 并清理分片。
+//
+// 保持追加不变量：合并时原有主台账行严格保持前缀不变，分片新行追加在末尾。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { mergeJsonlLines } from './git-merge-jsonl.mjs';
+
+const root = process.cwd();
+const mainLedger = path.join(root, '.agents', 'confirmations.jsonl');
+const shardDir = path.join(root, '.agents', 'confirmations.d');
+
+if (!fs.existsSync(shardDir) || !fs.statSync(shardDir).isDirectory()) {
+  console.log('[compact-ledgers] 未发现分片目录 .agents/confirmations.d/，无需打包。');
+  process.exit(0);
+}
+
+const shardFiles = fs.readdirSync(shardDir).filter((f) => f.endsWith('.jsonl')).sort();
+if (shardFiles.length === 0) {
+  console.log('[compact-ledgers] 分片目录无 .jsonl 文件，无需打包。');
+  process.exit(0);
+}
+
+console.log(`[compact-ledgers] 发现 ${shardFiles.length} 个分片文件，正在打包合并...`);
+
+const currentMain = fs.existsSync(mainLedger) ? fs.readFileSync(mainLedger, 'utf8') : '';
+let shardCombined = '';
+
+for (const file of shardFiles) {
+  const filePath = path.join(shardDir, file);
+  try {
+    shardCombined += '\n' + fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    console.error(`[compact-ledgers] 读取分片失败: ${file} (${err.message})`);
+    console.error('[compact-ledgers] 已中止打包：主台账与全部分片保持原样；请解决后重跑（合并按行去重，重跑安全）。');
+    process.exit(1);
+  }
+}
+
+const merged = mergeJsonlLines(currentMain, shardCombined);
+// 原子覆写主台账：直接 writeFileSync 会先截断原文件，进程中途崩溃将损坏主台账；
+// 改为同目录临时文件 + rename，任一步失败时主台账原样、分片未删，可安全重跑。
+const tmpMain = `${mainLedger}.tmp`;
+try {
+  fs.writeFileSync(tmpMain, merged, 'utf8');
+  fs.renameSync(tmpMain, mainLedger);
+} catch (err) {
+  try { fs.unlinkSync(tmpMain); } catch { /* tmp 可能尚未创建或删除失败 */ }
+  console.error(`[compact-ledgers] 主台账写入失败: ${err.message}`);
+  console.error('[compact-ledgers] 已中止打包：主台账原样、分片未删除；请解决后重跑（合并按行去重，重跑安全）。');
+  process.exit(1);
+}
+
+for (const file of shardFiles) {
+  try {
+    fs.unlinkSync(path.join(shardDir, file));
+  } catch { /* 忽略删除异常 */ }
+}
+
+// 若目录为空，尝试删除空目录
+try {
+  if (fs.readdirSync(shardDir).length === 0) {
+    fs.rmdirSync(shardDir);
+  }
+} catch { /* 忽略 */ }
+
+console.log(`[compact-ledgers] ✅ 打包完成！全量确认行已整合至 .agents/confirmations.jsonl，分片已清理。`);