agentic-flow-kit 0.2.0 → 0.3.0

package/src/init.mjs

@@ -4,8 +4,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { execSync, spawnSync } from 'node:child_process';
-import { renderTree, sha256 } from './render.mjs';
-import { HOSTS, STACKS, settingsJson, commitCheckConfig, pickStackVars, isOwned } from './profiles.mjs';
+import { renderTree, renderContent, sha256 } from './render.mjs';
+import { HOSTS, STACKS, STACK_ALIASES, settingsJson, commitCheckConfig, pickStackVars, isOwned } from './profiles.mjs';
 import { doctor } from './doctor.mjs';
 
 function fail(msg) {
@@ -42,21 +42,85 @@ function makePrompt() {
   };
 }
 
-// 交互确认环节：宿主多选 → 看板端口 → 显式确认（EOF / 非 y 一律取消，不装）
+// ---- TUI 风格：hand-rolled ANSI（零依赖纪律）；NO_COLOR / 非 TTY 自动降级纯文本 ----
+const RAW = !process.env.NO_COLOR && process.stdout.isTTY;
+const paint = (code, s) => (RAW ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = (s) => paint('1', s);
+const dim = (s) => paint('2', s);
+const cyan = (s) => paint('36', s);
+
+// normalizeStack：ts/js 用户口径归一为 node 栈；其余小写透传（STACKS 校验兜底未知值）
+export function normalizeStack(s) {
+  const t = String(s || '').trim().toLowerCase();
+  return STACK_ALIASES[t] || t;
+}
+
+// parseChoices：序号/名称/混输多选解析（逗号/全角逗号/空白分隔，去重保序）；
+// 空输入 → [def]（EOF/直接回车安全回退默认）；含非法 token 返回 null（调用方就地重问）；
+// map 用于输入侧归一（如 ts→node），序号先于 map 解析。
+export function parseChoices(input, names, def, map = (x) => x) {
+  const text = String(input || '').trim();
+  if (!text) return [def];
+  const out = [];
+  for (const tok of text.split(/[,，\s]+/).filter(Boolean)) {
+    const i = /^\d+$/.test(tok) ? Number(tok) - 1 : names.indexOf(map(tok.toLowerCase()));
+    if (!Number.isInteger(i) || i < 0 || i >= names.length) return null;
+    if (!out.includes(names[i])) out.push(names[i]);
+  }
+  return out;
+}
+
+// ---- AGENTS.md 骨架探测与追加补齐 ----
+// 标记随模板渲染落盘：新装/补齐后的 AGENTS.md 都含它，探测以此为准（不猜标题——避免误伤项目自写的同名「AI工作流」节）
+const SKELETON_MARKER = '<!-- flow-kit:agents-skeleton -->';
+export function hasAgentsSkeleton(text) {
+  return String(text || '').includes(SKELETON_MARKER);
+}
+// mergeAgents：原内容在上（尾部空白折叠），空行分隔，含标记的完整骨架在下
+export function mergeAgents(existing, incoming) {
+  const head = String(existing || '').replace(/\s+$/, '');
+  const tail = String(incoming || '').trim();
+  return head ? `${head}\n\n${tail}\n` : `${tail}\n`;
+}
+
+// 交互确认环节：序号菜单问答（宿主多选 → 技术栈 → 看板端口）→ 已选 recap → 显式确认
+// （EOF / 非 y 一律取消，不装；makePrompt 行式语义不变——管道/EOF 安全回退默认）
 async function interactive() {
   const p = makePrompt();
-  console.log('▶ flow-kit init（交互模式——裸跑无参数时进入；带参数则直接执行，见 flow-kit --help）');
-  console.log('  将在当前目录安装：.agents/ ｜ .githooks/ ｜ workflow/ ｜ wiki/ ｜ AGENTS.md（已存在的文件保守跳过）');
+  const hostNames = Object.keys(HOSTS);
+  const stackNames = Object.keys(STACKS);
+  const stackLabel = (n) => (n === 'node' ? 'node（ts/js）' : n);
+  const menu = (names) => '  ' + names.map((n, i) => dim(`${'①②③④⑤⑥'[i]} ${stackLabel(n)}`)).join(dim('   '));
+
+  console.log(bold(cyan('▶ flow-kit init')) + dim(' · AI 闭环工作流 + wiki 知识层脚手架'));
+  console.log(dim('  安装到当前目录：.agents/ · .githooks/ · workflow/ · wiki/ · AGENTS.md（已存在的文件保守跳过；AGENTS.md 无工作流骨架时文末追加补齐）'));
   try {
-    const hosts = await p.ask('1/3 选择 agent 宿主（逗号分隔：zcode / opencode / trae / omp）', 'zcode');
-    const stack = await p.ask('2/3 技术栈——决定编译检查与自检验命令初值（dotnet / node / python / go / none）', 'none');
-    const boardPort = await p.ask('3/3 workflow 看板端口', '8933');
-    const yes = await p.ask('确认安装到当前目录？(y/n)');
+    let hosts;
+    for (;;) {
+      console.log(`\n${cyan('── 1/3 · agent 宿主')} ${dim('· 可多选')}`);
+      console.log(menu(hostNames));
+      const picked = parseChoices(await p.ask(dim('  序号或名称，逗号分隔（直接回车 = zcode）')), hostNames, hostNames[0]);
+      if (picked) { hosts = picked; break; }
+      console.log(dim('  ⚠️ 没认出这个组合——序号或名称再来一次（如 1,3 或 zcode,trae）'));
+    }
+    let stack;
+    for (;;) {
+      console.log(`\n${cyan('── 2/3 · 技术栈')} ${dim('· 决定编译检查与自检验命令初值')}`);
+      console.log(menu(stackNames));
+      const picked = parseChoices(await p.ask(dim('  序号或名称（直接回车 = none；ts/js 自动归一 node）')), stackNames, 'none', normalizeStack);
+      if (picked) { stack = picked[0]; break; }
+      console.log(dim('  ⚠️ 没认出——序号或名称再来一次'));
+    }
+    console.log(`\n${cyan('── 3/3 · workflow 看板端口')}`);
+    const boardPort = (await p.ask(dim('  直接回车 = 8933'))) || '8933';
+
+    console.log(`\n  ${bold(`宿主 ${hosts.join('、')}`)}${dim(' ｜ ')}${bold(`技术栈 ${stack}`)}${dim(' ｜ ')}${bold(`端口 ${boardPort}`)}`);
+    const yes = await p.ask(dim('  确认安装到当前目录？(y/n，回车取消)'));
     if (!/^(y|yes)$/i.test(yes)) {
       console.log('已取消（未做任何改动）');
       process.exit(0);
     }
-    return { hosts, stack, boardPort, dir: process.cwd(), force: false };
+    return { hosts: hosts.join(','), stack, boardPort, dir: process.cwd(), force: false };
   } finally {
     p.close();
   }
@@ -84,7 +148,8 @@ export async function init(args, pkgRoot) {
     }
   }
 
-  if (!STACKS[opt.stack]) fail(`未知技术栈：${opt.stack}（可选 dotnet | node | python | go | none——对应编译检查与自检验命令初值）`);
+  opt.stack = normalizeStack(opt.stack);
+  if (!STACKS[opt.stack]) fail(`未知技术栈：${opt.stack}（可选 dotnet | node（ts/js） | python | go | none——对应编译检查与自检验命令初值）`);
   const hosts = opt.hosts.split(',').map((s) => s.trim()).filter(Boolean);
   for (const h of hosts) {
     if (!HOSTS[h]) fail(`未知宿主：${h}（可选 ${Object.keys(HOSTS).join(' | ')}）`);
@@ -99,11 +164,29 @@ export async function init(args, pkgRoot) {
 
   const vars = { BOARD_PORT: String(opt.boardPort), ...pickStackVars(opt.stack) };
 
-  console.log(`▶ flow-kit init → ${target}`);
+  console.log(`${bold(cyan('▶ flow-kit init'))}${dim(' → ')}${target}`);
   console.log(`  宿主：${hosts.join(', ')} ｜ 技术栈：${opt.stack} ｜ 看板端口：${opt.boardPort}`);
 
   // 1) 模板树（保守：已存在文件跳过，--force 覆盖）
   const t = renderTree(path.join(pkgRoot, 'templates'), target, vars, { force: opt.force });
+
+  // 1.5) AGENTS.md 特例：已存在且无骨架标记 → 文末追加补齐（原内容保留）；带标记 → 保守跳过
+  let agentsMergedSha = null;
+  if (t.skipped.includes('AGENTS.md')) {
+    const agentsAbs = path.join(target, 'AGENTS.md');
+    const existing = fs.readFileSync(agentsAbs, 'utf8');
+    if (hasAgentsSkeleton(existing)) {
+      t.skipped = t.skipped.filter((r) => r !== 'AGENTS.md'); // 专属提示已报，不进末尾「未覆盖」汇总重复列
+      console.log('  跳过（已存在且含工作流骨架）：AGENTS.md');
+    } else {
+      const incoming = renderContent(fs.readFileSync(path.join(pkgRoot, 'templates', 'AGENTS.md'), 'utf8'), vars);
+      fs.writeFileSync(agentsAbs, mergeAgents(existing, incoming));
+      agentsMergedSha = sha256(fs.readFileSync(agentsAbs));
+      t.skipped = t.skipped.filter((r) => r !== 'AGENTS.md');
+      console.log('  AGENTS.md 已存在但无工作流骨架——文末追加补齐（原内容保留，「项目适配区」照常自填）');
+    }
+  }
+
   // 2) 宿主适配层
   const hostResults = {};
   for (const h of hosts) {
@@ -155,6 +238,7 @@ export async function init(args, pkgRoot) {
     ...hosts.flatMap((h) => hostResults[h].written.map((f) => ({ ...f, rel: `${HOSTS[h].dir}/${f.rel}` }))),
   ];
   const owned = [...t.written.filter((f) => isOwned(f.rel)), ...ownedGenerated];
+  if (agentsMergedSha) owned.push({ rel: 'AGENTS.md', sha256: agentsMergedSha });
   const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
   fs.mkdirSync(path.dirname(kitPath), { recursive: true });
   fs.writeFileSync(kitPath, `${JSON.stringify({

package/src/init.test.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// init.mjs 交互解析纯函数测试（normalizeStack / parseChoices）——不触真实安装与 stdin
+// 断言：①ts/js 别名归一 node；②序号/名称/混输/全角逗号/空白分隔解析正确（去重保序）；
+//       ③非法输入返回 null（就地重问信号）；④空输入回默认（EOF/直接回车安全回退）。
+// 用法：node src/init.test.mjs
+import { normalizeStack, parseChoices, hasAgentsSkeleton, mergeAgents } from './init.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 HOSTS = ['zcode', 'opencode', 'trae', 'omp'];
+const STACKS = ['dotnet', 'node', 'python', 'go', 'none'];
+const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// ---- ① 别名归一 ----
+check('ts/TS/TypeScript/javascript 均归一 node', normalizeStack('ts') === 'node' && normalizeStack('TS') === 'node' && normalizeStack('TypeScript') === 'node' && normalizeStack('javascript') === 'node');
+check('规范名与空值透传', normalizeStack('node') === 'node' && normalizeStack('dotnet') === 'dotnet' && normalizeStack('  go ') === 'go' && normalizeStack('') === '' && normalizeStack(undefined) === '');
+
+// ---- ② 序号/名称/混输解析 ----
+check('序号 1,3 → zcode,trae', eq(parseChoices('1,3', HOSTS, 'zcode'), ['zcode', 'trae']));
+check('名称 trae → trae', eq(parseChoices('trae', HOSTS, 'zcode'), ['trae']));
+check('混输 zcode，3（全角逗号）→ zcode,trae', eq(parseChoices('zcode，3', HOSTS, 'zcode'), ['zcode', 'trae']));
+check('空白分隔 1 3 → zcode,trae', eq(parseChoices('1 3', HOSTS, 'zcode'), ['zcode', 'trae']));
+check('去重保序 3,1,1 → trae,zcode', eq(parseChoices('3,1,1', HOSTS, 'zcode'), ['trae', 'zcode']));
+check('栈序号 2 + map 归一 → node', eq(parseChoices('2', STACKS, 'none', normalizeStack), ['node']));
+check('栈别名 ts + map 归一 → node', eq(parseChoices('ts', STACKS, 'none', normalizeStack), ['node']));
+
+// ---- ③ 非法输入 → null（就地重问） ----
+check('越界序号 9 → null', parseChoices('9', HOSTS, 'zcode') === null);
+check('未知名称 bad → null', parseChoices('zcode,bad', HOSTS, 'zcode') === null);
+check('栈别名未传 map 不归一（ts → null）', parseChoices('ts', STACKS, 'none') === null);
+
+// ---- ④ 空输入回默认 ----
+check('空串 → [def]', eq(parseChoices('', HOSTS, 'zcode'), ['zcode']));
+check('undefined → [def]', eq(parseChoices(undefined, STACKS, 'none'), ['none']));
+
+// ---- ⑤ AGENTS.md 骨架探测与合并 ----
+check('标记探测：带标记 true', hasAgentsSkeleton('x\n<!-- flow-kit:agents-skeleton -->\n# y') === true);
+check('标记探测：外部自写 AGENTS.md false', hasAgentsSkeleton('# 我的项目\n\n构建: dotnet build') === false);
+check('标记探测：空值 false', hasAgentsSkeleton('') === false && hasAgentsSkeleton(undefined) === false);
+check('合并：原内容在上、空行分隔、骨架在下',
+  mergeAgents('# A\n内容', '<!-- m -->\n# B') === '# A\n内容\n\n<!-- m -->\n# B\n');
+check('合并：原内容尾部空白折叠不产生连续空行',
+  mergeAgents('# A\n内容\n\n\n', '<!-- m -->\n# B') === '# A\n内容\n\n<!-- m -->\n# B\n');
+check('合并：原内容为空时骨架即全文', mergeAgents('', '<!-- m -->\n# B') === '<!-- m -->\n# B\n');
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) {
+  console.log('\n用法：node src/init.test.mjs');
+  process.exit(1);
+}
+process.exit(0);

package/src/profiles.mjs

@@ -62,6 +62,14 @@ export const STACKS = {
   },
 };
 
+// 技术栈别名归一：ts/js 用户口径 → node 栈（init 交互与 --stack 共用；别名不进 kit.json，落盘始终是规范名）
+export const STACK_ALIASES = {
+  ts: 'node',
+  js: 'node',
+  typescript: 'node',
+  javascript: 'node',
+};
+
 // AGENTS.md「项目适配区」的命令预填变量（技术栈未知时留 <填写> 占位）
 export function pickStackVars(stackKey) {
   const s = STACKS[stackKey] || STACKS.none;

package/src/render.mjs

@@ -17,6 +17,11 @@ function relOf(absFile, srcRoot) {
   return parts.join('/');
 }
 
+// renderContent：单文件文本渲染（{{KEY}} 替换，未知占位符原样保留）——renderTree 与 init 的 AGENTS.md 追加补齐共用
+export function renderContent(text, vars) {
+  return String(text || '').replace(PH_RE, (m, key) => (Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : m));
+}
+
 export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
   const written = [];   // { rel, sha256 }
   const skipped = [];   // rel（已存在，保守跳过）
@@ -27,6 +32,8 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const abs = path.join(dir, entry.name);
       if (entry.isDirectory()) {
+        // 运行时缓存不是模板（包源跑测试会在 templates/_agents/cache/ 落盘残留）——init/sync 一律跳过
+        if (relOf(abs, srcRoot) === '.agents/cache') continue;
         dirs.push(relOf(abs, srcRoot));
         walk(abs);
         continue;
@@ -41,15 +48,7 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
       const raw = fs.readFileSync(abs);
       let out = raw;
       if (raw.length < 512 * 1024 && !raw.includes(0)) {
-        const text = raw.toString('utf8');
-        const used = new Set();
-        const replaced = text.replace(PH_RE, (m, key) => {
-          if (Object.prototype.hasOwnProperty.call(vars, key)) {
-            used.add(key);
-            return vars[key];
-          }
-          return m; // 未知占位符原样保留，doctor 会告警
-        });
+        const replaced = renderContent(raw.toString('utf8'), vars);
         if (replaced.includes('{{')) {
           for (const m of replaced.matchAll(/\{\{([A-Z][A-Z0-9_]*)\}\}/g)) {
             if (!Object.prototype.hasOwnProperty.call(vars, m[1])) warnings.push(`${rel}: 未知占位符 {{${m[1]}}}（原样保留）`);

package/src/run-tests.mjs

@@ -9,6 +9,7 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 const nodeSuites = [
   'src/sync.test.mjs',
+  'src/init.test.mjs',
   ...fs.readdirSync(path.join(ROOT, 'templates/_agents/scripts'))
     .filter((f) => f.endsWith('.test.mjs'))
     .sort()

package/src/sync.mjs

@@ -1,5 +1,6 @@
 // flow-kit sync：按 .agents/kit.json 台账升级 managed 文件。
-// 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖）；
+// 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖；台账保持包侧基线，
+//       每次持续报告直至 --force 或本地对齐新版——防跳过一次后下次升级被静默覆盖，2026-09-24 语义修正）；
 //       生成器目标（INDEX.md / wiki 看板）→ 不比对，收尾重跑生成器走锚点重写。
 // 附带：包内新增 managed 文件 → 安装；包内已删 → 仅报告不删盘、出台账；managed 缺失 → 恢复。
 // owned 文件永不触碰（两态模型，见 profiles.isOwned）。
@@ -86,7 +87,7 @@ export function sync(args, pkgRoot) {
       // 本地已改
       if (freshFile.sha === diskSha) { unchanged++; managedNew.push({ rel, sha256: diskSha }); continue; } // 改动恰好等于新版
       if (force) { fs.copyFileSync(freshFile.abs, disk); updated.push(`${rel}（--force 覆盖本地改动）`); managedNew.push({ rel, sha256: freshFile.sha }); }
-      else { skipped.push(rel); managedNew.push({ rel, sha256: diskSha }); } // 台账跟随磁盘，下次以当前盘面为基线
+      else { skipped.push(rel); managedNew.push({ rel, sha256: ledgerSha }); } // 台账保持包侧基线：持续报告「本地已改」，直到 --force 或本地对齐新版
     }
 
     // 台账外的新文件：managed 类安装；owned 类只对「盘上缺失」的起步文档报告（已装的不动不报）
@@ -109,7 +110,7 @@ export function sync(args, pkgRoot) {
     list('恢复缺失', restored);
     list('新增安装', added);
     list('本地已改，跳过', skipped);
-    if (skipped.some((s) => !s.includes('未入台账'))) console.log('    ↑ --force 覆盖本地改动；git diff 自查差异');
+    if (skipped.some((s) => !s.includes('未入台账'))) console.log('    ↑ --force 覆盖本地改动；git diff 自查差异；台账保持包侧基线，后续 sync 持续报告直至处理');
     list('包内已移除（文件保留在盘上，可手动删除）', removed);
     list('新增 owned 起步文档（项目自持，未自动安装）', newOwned);
     if (!updated.length && !restored.length && !added.length && !removed.length && !skipped.length && !newOwned.length) {
@@ -118,7 +119,22 @@ export function sync(args, pkgRoot) {
       console.log(`  无变化 ${unchanged} 份`);
     }
 
-    // 台账重写：版本对齐当前包；removed 出册；skipped 盘面基线化
+    // owned 台账按盘面自愈：owned 归项目所有，哈希只是记账不是约束——手改后无须手工刷 kit.json
+    // （Shipyard 回流策略，2026-09-24：曾在消费仓被迫手工刷新 owned 哈希，根因收敛到此处）
+    let ownedRefreshed = 0;
+    if (Array.isArray(kit.owned)) {
+      kit.owned = kit.owned.map((f) => {
+        const p = path.join(target, f.rel);
+        if (!fs.existsSync(p)) return f;
+        const disk = sha256(fs.readFileSync(p));
+        if (disk === f.sha256) return f;
+        ownedRefreshed++;
+        return { ...f, sha256: disk };
+      });
+    }
+    if (ownedRefreshed) console.log(`  owned 台账哈希按盘面刷新 ${ownedRefreshed} 份（owned 归项目所有，仅记账不约束）`);
+
+    // 台账重写：版本对齐当前包；removed 出册；skipped 保持包侧基线持续报告
     kit.managed = managedNew.sort((a, b) => a.rel.localeCompare(b.rel));
     kit.version = pkg.version;
     fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);

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

@@ -1,3 +1,4 @@
+<!-- flow-kit:agents-skeleton -->
 # AGENTS.md — AI 工作流 + Wiki
 
 > 本文件由 agentic-flow-kit 生成：说明本仓库的 AI 工作流与 Wiki 用法。「项目适配区」由项目自行填写；工作流约定可增不可删。
@@ -25,12 +26,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`，不当场顺手改。
 
 ### 验证与关单