agentic-flow-kit 0.2.0 → 0.2.1

package/src/sync.test.mjs

@@ -94,7 +94,7 @@ else if (cmd === 'add-gate') addGate(rest, root);
   const rels = kit.managed.map((f) => f.rel);
   check('S1 台账：版本对齐包版本', kit.version === '9.9.9');
   check('S1 台账：gone 出册、new 入册', !rels.includes('.agents/scripts/gone.txt') && rels.includes('.agents/commands/new.txt'));
-  check('S1 台账：跳过文件基线化为用户版 sha', kit.managed.find((f) => f.rel === '.agents/scripts/loc.txt').sha256 === sha256(Buffer.from('loc USER\n')));
+  check('S1 台账：跳过文件保持包侧基线 sha（持续报告，不随盘面基线化）', kit.managed.find((f) => f.rel === '.agents/scripts/loc.txt').sha256 === sha256(Buffer.from('loc v1\n')));
   check('S1 台账：覆盖文件 sha 为新版', kit.managed.find((f) => f.rel === '.agents/scripts/chg.txt').sha256 === sha256(Buffer.from('chg v2 port 777\n')));
   check('S1 owned 不触碰（AGENTS.md 原样）', R(path.join(t, 'AGENTS.md')) === 'owned skeleton v2\n');
   check('S1 已装 owned 不误报新增', !out.includes('新增 owned 起步文档'), out);
@@ -182,6 +182,10 @@ else if (cmd === 'add-gate') addGate(rest, root);
   check('S8 local-pre-commit 接线（缺失则建 set -e 头）', R(path.join(t, '.agents/hooks/local-pre-commit')) === '#!/bin/sh\nset -e\nsh .agents/hooks/gate.sh\n', out);
   const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
   check('S8 owned 台账补记（归项目所有）', kit.owned.some((f) => f.rel === '.agents/hooks/gate.sh'));
+  check('S8 接线后 local-pre-commit 进 owned 且哈希=盘面（Shipyard 回流根因，2026-09-24）', (() => {
+    const e = kit.owned.find((f) => f.rel === '.agents/hooks/local-pre-commit');
+    return e && e.sha256 === sha256(Buffer.from(R(path.join(t, '.agents/hooks/local-pre-commit')), 'utf8'));
+  })(), JSON.stringify(kit.owned));
   runCmd('add-gate', fx, t, ['fakeg']); // 再跑一遍
   check('S8 幂等：接线行不重复', R(path.join(t, '.agents/hooks/local-pre-commit')) === '#!/bin/sh\nset -e\nsh .agents/hooks/gate.sh\n');
   const r3 = runCmd('add-gate', fx, t, ['nope']);
@@ -203,5 +207,40 @@ else if (cmd === 'add-gate') addGate(rest, root);
   check('S9 挂载行在 exit 0 原位之前追加', R(path.join(t, '.agents/hooks/local-pre-commit')) === '#!/bin/sh\n# 旧装态注释\nsh .agents/hooks/gate.sh\n', R(path.join(t, '.agents/hooks/local-pre-commit')));
 }
 
+// ============ 场景 10：模板树内的运行时缓存不进安装与台账 ============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/cache/kb-index.json'), '{"stale":"test-residue"}');
+  const t = mkTarget(fx); // v1 安装态无 cache 文件
+  const r = runCmd('sync', fx, t);
+  check('S10 cache 残留不被安装', !fs.existsSync(path.join(t, '.agents/cache/kb-index.json')), r.stdout + r.stderr);
+  const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  check('S10 cache 不入 managed 台账', !kit.managed.some((f) => f.rel.startsWith('.agents/cache/')), JSON.stringify(kit.managed.filter((f) => f.rel.includes('cache'))));
+}
+
+// ============ 场景 11：跳过件不被下次升级静默覆盖（台账保持包侧基线，2026-09-24 语义修正回归） ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  W(path.join(t, '.agents/scripts/loc.txt'), 'loc USER\n');
+  runCmd('sync', fx, t); // 第一次：本地已改 → 跳过
+  W(path.join(fx, 'templates/_agents/scripts/loc.txt'), 'loc v3\n'); // 包再出新版
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S11 二次 sync 不覆盖本地改动（loc.txt 仍为用户版）', R(path.join(t, '.agents/scripts/loc.txt')) === 'loc USER\n', out);
+  check('S11 仍按「本地已改，跳过」报告', out.includes('本地已改，跳过') && out.includes('loc.txt'), out);
+}
+
+// ============ 场景 12：owned 台账哈希按盘面自愈（Shipyard 回流策略，2026-09-24） ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  W(path.join(t, 'AGENTS.md'), 'owned skeleton v2 EDITED BY USER\n'); // owned 件手改 → 台账停旧值
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S12 owned 文件不被触碰（AGENTS.md 保持用户版）', R(path.join(t, 'AGENTS.md')) === 'owned skeleton v2 EDITED BY USER\n', out);
+  const kit = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  check('S12 owned 台账哈希自愈为盘面值', kit.owned.find((f) => f.rel === 'AGENTS.md').sha256 === sha256(Buffer.from('owned skeleton v2 EDITED BY USER\n')), JSON.stringify(kit.owned));
+  check('S12 有刷新报告', out.includes('owned 台账哈希按盘面刷新 1 份'), out);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
 process.exit(failCount ? 1 : 0);

package/templates/AGENTS.md

@@ -25,12 +25,12 @@
 - `.githooks/`（经 `core.hooksPath` 挂载，本地 clone 后执行 `git config core.hooksPath .githooks`）：pre-commit（闭环配对 / wiki 台账 / 规则面预算 / 敏感信息扫描与条件构建）、pre-push（闭环断档扫描）、commit-msg、post-commit、pre-merge-commit。
 - **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规，按提示修完原路重试。
 - 项目专属门禁挂 `.agents/hooks/local-pre-commit`。
-- 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）；L1+ 入口文档 / spec / plan 随代码同一提交。
+- 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）；L1+ 入口文档 / spec / plan 随代码同一提交；确认（approved）后立即 `docs(*)` 单独提交留痕。
 
 ### 检索、看板与量化
 
 - 跨语料检索：`node .agents/scripts/kb-search.mjs "<词>"`（workflow 节级定位 + wiki 全文）；活跃流程读 `workflow/INDEX.md`（状态变更后 `node .agents/scripts/gen-workflow-index.mjs` 重生成）。
-- workflow 看板：http://127.0.0.1:{{BOARD_PORT}}（任务入口幂等拉起 ensure-board；只读预警层，非门禁）。
+- workflow 看板（可选，默认不拉起）：需要时手动跑 `.agents/scripts/ensure-board.ps1`，然后访问 http://127.0.0.1:{{BOARD_PORT}}（只读预警层，非门禁）。
 - 委派 / 自做结果留痕 `workflow/delegations.md`（聚合 `node .agents/scripts/agg-delegations.cjs`）；命令 / 技能卡壳记 `workflow/papercuts.md`，不当场顺手改。
 
 ### 验证与关单