@xulthekl/team-flow 0.56.1 → 0.57.0

package/scripts/lib/solutions-index-gen.mjs

@@ -1,69 +1,105 @@
 #!/usr/bin/env node
 /**
- * solutions-index-gen — 扫描 docs/solutions/<phase>/ 各阶段目录，重建 INDEX.md
+ * solutions-index-gen — 扫描 docs/solutions/<phase>/ 重建 INDEX.md
  *
- * v0.5 复利贯穿机制脚本
+ * v0.5 复利贯穿机制脚本；v0.57.0 §4.2 重构为共享入口
  * 用法：tf solutions index-gen [--dir <solutions-dir>]
  *
  * 功能：
- * 1. 扫描 docs/solutions/ 下所有子目录中的 .md 文件
- * 2. 解析每个文件的 frontmatter（phase/domain/type/severity/date/summary）
- * 3. 按 severity 降序、date 降序排列
- * 4. 重建 INDEX.md（≤150 行硬上限）
- * 5. 超出 150 条时，淘汰 low severity 且 date 最早的条目
+ * 1. 扫描 docs/solutions/<phase>/ 下的 .md 文件（phase 枚举见 solutions-phases.mjs）
+ * 2. 解析 frontmatter（phase/domain/type/severity/date，以及可选的 title）
+ * 3. 按 severity 降序 → date 降序 → file 兜底排列（末键保证同日同 severity 的去留可复现）
+ * 4. 重建 INDEX.md（≤ MAX_INDEX_ENTRIES 条）
+ * 5. 超出上限时按序保留前 N 条，其余**保留在磁盘**并计入 dropped
+ *
+ * v0.57.0 §4.2 变更（设计文档 compound-lifecycle-governance-design v2.2）：
+ * - **抽 `refreshIndex()` 为共享入口**：capture / promote 在写完条目文件后**各自内部调用**，
+ *   取代 v2.1 的"在调用点逐一追加"——promote 有 5 处调用点、capture 有 4 处，逐处追加必然漏改。
+ * - **目录缺失时创建**（原直接 `exit 1`）：改由 capture/promote 调用后，首次使用时
+ *   `docs/solutions/` 可能尚不存在，失败会让整条晋升链中断。
+ * - **severity 单向取自条目文件**：INDEX 是**投影**。设计曾考虑"重建时取 max(旧 INDEX, 文件)"
+ *   以防升级丢失——已**否决**：那会让 INDEX 成为并列真值源，把漂移固化为不可降档的不变量。
+ * - summary 优先取 frontmatter 的 `title:`（v0.57.0 起 CLI 条目会写），无则回退正文首行。
+ * - 截断由**静默**改为 **WARN + dropped 明细**（截断从"从未触发"变为"每次晋升必经"）。
+ *
+ * v0.57.0 P4 修复（评审轮 M2/M3/m4）：
+ * - **单元格转义**：内容含 `|` 会让该行列数膨胀 ⇒ 消费方列数校验丢弃整行 ⇒ 条目隐身，
+ *   且 doctor 的修复建议（重跑 index-gen）产出同一坏行，形成死循环。见 `escapeCell`。
+ * - **加 `source` 列**（7→8）：同源聚类的聚类键。inject 约定"只读 INDEX 不读条目文件"，
+ *   故 source 必须进索引才可用。
+ * - **排序补 file 兜底键**：同日同 severity 的去留在 maxEntries 边界上原本不可复现。
  */
 
-import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { severityRank } from './severity.mjs';
 import { SOLUTION_PHASES } from './solutions-phases.mjs';
+// frontmatter 读取的**共享实现**（含行尾注释剥离）——已知例外与理由见 solutions-entry 的 docstring
+import { parseFrontmatter, listSolutionEntries } from './solutions-entry.mjs';
 
-const MAX_INDEX_LINES = 150;
-
-function parseFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return null;
-  const fm = {};
-  for (const line of match[1].split('\n')) {
-    const idx = line.indexOf(':');
-    if (idx > 0) {
-      const key = line.slice(0, idx).trim();
-      const val = line.slice(idx + 1).trim();
-      fm[key] = val;
-    }
-  }
-  return fm;
+/** INDEX 保留的最大**条目数**（非行数——文件还含 4 行头部） */
+export const MAX_INDEX_ENTRIES = 150;
+
+/**
+ * 解析条目文件的 frontmatter（扁平键值）——**收敛到共享层**（v0.57.0 P4 二轮）。
+ *
+ * 原实现在此**裸读**、不剥行尾注释，后果不是"显示难看"而是静默错判：
+ * 注释值原样进 INDEX ⇒ `severityRank` 落未知值档 ⇒ 高危条目排到 `low` 之后、
+ * 在 `--limit` 窗口下最先被截掉。
+ *
+ * 注意必须**先 import 再 export**：`export { X } from '...'` 只做转发，
+ * **不会**在本模块作用域建立绑定，而 `refreshIndex` 内部正要调用它。
+ * 保留本名导出以兼容既有消费者（`cmd-doctor` 等）。
+ */
+export { parseFrontmatter };
+
+/**
+ * 转义 INDEX 表格单元格（v0.57.0 P4 修复）。
+ *
+ * 不转义的后果**比"脏"严重**：summary 含一个 `|` ⇒ 该行列数变 8 ⇒ 消费方
+ * （`solutions-inject` / `cmd-doctor`）的列数校验直接丢弃整行 ⇒ 条目**永久隐身**。
+ * 更糟的是 `tf doctor` 报出漂移后建议"运行 index-gen 重建"，而重建会产出同一坏行
+ * ⇒ **修复建议永不生效的死循环**（v0.38.0 test-merge 同型缺陷的另一面）。
+ *
+ * 换行也压平：表格行内含 `\n` 会把一行表格炸成两行。
+ */
+function escapeCell(value) {
+  return String(value ?? '')
+    .replace(/\|/g, '\\|')
+    .replace(/\s+/g, ' ')
+    .trim();
 }
 
-function extractSummary(content) {
-  // 取 frontmatter 后第一个非空行作为摘要
+function extractSummary(content, fm) {
+  // v0.57.0：优先取 frontmatter 的 title（CLI 条目自本版起写该字段）；
+  // 回退"frontmatter 后第一个非空行"——但正文首行常是 `- **教训来源**：…` 型元数据，
+  // 故回退路径的摘要质量低于 title。
+  if (fm?.title) return String(fm.title).slice(0, 80);
   const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
   const lines = body.split('\n').filter(l => l.trim() && !l.startsWith('#'));
   return lines[0]?.trim().slice(0, 80) || '(no summary)';
 }
 
-export function run(args = {}) {
-  const dir = args.dir || 'docs/solutions';
-  const indexPath = join(dir, 'INDEX.md');
-
-  if (!existsSync(dir)) {
-    console.error(`Solutions directory not found: ${dir}`);
-    process.exit(1);
-  }
+/**
+ * 重建 `docs/solutions/INDEX.md` —— capture / promote / CLI 共用的**唯一** INDEX 写入入口。
+ *
+ * @param {string} dir solutions 根目录
+ * @param {{phases?: readonly string[], maxEntries?: number, quiet?: boolean}} [options]
+ * @returns {{kept: number, dropped: number, droppedEntries: Array<{file: string, severity: string, date: string}>}}
+ */
+export function refreshIndex(dir, { phases = SOLUTION_PHASES, maxEntries = MAX_INDEX_ENTRIES, quiet = false } = {}) {
+  // 目录缺失时创建（原实现 exit 1 —— 会让首次晋升链中断）
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
   const entries = [];
 
-  for (const phase of SOLUTION_PHASES) {
-    const phaseDir = join(dir, phase);
-    if (!existsSync(phaseDir) || !statSync(phaseDir).isDirectory()) continue;
-
-    for (const file of readdirSync(phaseDir)) {
-      if (!file.endsWith('.md')) continue;
-      const filePath = join(phaseDir, file);
-      const content = readFileSync(filePath, 'utf-8');
+  for (const phase of phases) {
+    // 条目枚举走**共享层**（与 `cmd-doctor` / `backfill` 同源）：它同时承担
+    // ①条目判据（判据不一致会让 doctor 报出重跑 index-gen 也消不掉的告警）
+    // ②防御（非普通文件 / 读失败不再让整批枚举抛异常）
+    for (const { file, content } of listSolutionEntries(join(dir, phase))) {
       const fm = parseFrontmatter(content);
-      if (!fm) continue;
 
       entries.push({
         date: fm.date || '1970-01-01',
@@ -71,37 +107,61 @@ export function run(args = {}) {
         domain: fm.domain || 'general',
         type: fm.type || 'insight',
         severity: fm.severity || 'low',
-        summary: extractSummary(content),
+        summary: extractSummary(content, fm),
         file: `${phase}/${file}`,
+        // v0.57.0 P4：source 进 INDEX 供 inject 做同源聚类（此前只存在于条目文件，消费方读不到）
+        source: fm.source || '',
       });
     }
   }
 
-  // 排序：severity 降序，date 降序
+  // 排序：severity 降序，date 降序，**文件名兜底**
+  // v0.57.0 P4：前两键相同时（同日同 severity 极常见）去留取决于 readdirSync 顺序，
+  // 在 maxEntries 边界上跨机器/跨文件系统不可复现 ⇒ 补 file 作为决定性末键。
   entries.sort((a, b) => {
     const sevDiff = severityRank(a.severity) - severityRank(b.severity);
     if (sevDiff !== 0) return sevDiff;
-    return b.date.localeCompare(a.date);
+    const dateDiff = b.date.localeCompare(a.date);
+    if (dateDiff !== 0) return dateDiff;
+    return a.file.localeCompare(b.file);
   });
 
-  // 截断到 150 条
-  const kept = entries.slice(0, MAX_INDEX_LINES);
-  const dropped = entries.slice(MAX_INDEX_LINES);
+  const kept = entries.slice(0, maxEntries);
+  const droppedEntries = entries.slice(maxEntries);
 
-  // 生成 INDEX.md
+  // v0.57.0 P4：加 `source` 列（7→8）——同源聚类需要它，而 inject 的设计约定是
+  // "只读 INDEX、不读条目文件"，故聚类键必须进索引。消费方对 7/8 列都容错（见 solutions-inject）。
   let index = '# Solutions Index\n';
-  index += '<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->\n';
-  index += '| date | phase | domain | type | severity | summary | file |\n';
-  index += '|------|-------|--------|------|----------|---------|------|\n';
+  index += `<!-- 每条一行，排序 severity 降序 → date 降序 → file 兜底，≤${maxEntries} 条上限；summary/source 内的 | 转义为 \\| -->\n`;
+  index += '| date | phase | domain | type | severity | summary | file | source |\n';
+  index += '|------|-------|--------|------|----------|---------|------|--------|\n';
   for (const e of kept) {
-    index += `| ${e.date} | ${e.phase} | ${e.domain} | ${e.type} | ${e.severity} | ${e.summary} | ${e.file} |\n`;
+    index += `| ${escapeCell(e.date)} | ${escapeCell(e.phase)} | ${escapeCell(e.domain)} | ${escapeCell(e.type)} | ${escapeCell(e.severity)} | ${escapeCell(e.summary)} | ${escapeCell(e.file)} | ${escapeCell(e.source)} |\n`;
   }
 
-  writeFileSync(indexPath, index, 'utf-8');
-  console.log(`INDEX.md rebuilt: ${kept.length} entries (${dropped.length} dropped)`);
-  if (dropped.length > 0) {
-    console.log(`Dropped ${dropped.length} low-priority entries (files preserved in directories)`);
+  writeFileSync(join(dir, 'INDEX.md'), index, 'utf-8');
+
+  if (!quiet) {
+    console.log(`INDEX.md rebuilt: ${kept.length} entries (${droppedEntries.length} dropped)`);
   }
+  if (droppedEntries.length > 0) {
+    console.warn(`⚠ ${droppedEntries.length} 条经验超出 INDEX 上限（${maxEntries} 条），未被索引（文件保留在磁盘）：`);
+    for (const e of droppedEntries) {
+      console.warn(`  - [${e.severity}] ${e.date} ${e.file}`);
+    }
+    console.warn('  处置建议：提升关键条目 severity，或归档低价值条目（见设计文档 §3.3 退役语义）');
+  }
+
+  return {
+    kept: kept.length,
+    dropped: droppedEntries.length,
+    droppedEntries: droppedEntries.map(e => ({ file: e.file, severity: e.severity, date: e.date })),
+  };
+}
+
+export function run(args = {}) {
+  const dir = args.dir || 'docs/solutions';
+  refreshIndex(dir);
 }
 
 // CLI 直接执行

package/scripts/lib/solutions-inject.mjs

@@ -1,75 +1,153 @@
 #!/usr/bin/env node
 /**
- * solutions-inject — 按 phase+domain 过滤 INDEX.md，输出 top-5 摘要
+ * solutions-inject — 按 phase+domain 过滤 INDEX.md，输出经验摘要供 skill 注入上下文
  *
  * v0.5 复利贯穿机制脚本
- * 用法：tf solutions inject --phase <p> --domain <d>
+ * 用法：tf solutions inject --phase <p> [--domain <d>] [--limit <n> | --all]
  *
  * 功能：
- * 1. 读取 docs/solutions/INDEX.md
- * 2. 过滤：phase = 指定阶段 OR phase = cross-phase，且 domain 匹配
- * 3. 按 severity 降序取 top-5
- * 4. 输出摘要（供各 skill 注入上下文）
+ * 1. 读取 docs/solutions/INDEX.md（**只读 INDEX，不读条目文件**）
+ * 2. 过滤：phase = 指定阶段 OR phase = cross-phase（**cross-phase 是通配符**），且 domain 匹配
+ * 3. 排序：severity 降序 → 阶段匹配度（本阶段优先于通配）→ date 降序
+ * 4. 输出前 N 条（默认 5）摘要
+ *
+ * v0.57.0 §4.1 变更（设计文档 compound-lifecycle-governance-design v2.2）：
+ * - **`--phase` 语义**：`ePhase === phase || ePhase === 'cross-phase'`——cross-phase 是**通配符**，
+ *   不是"仅本阶段"。故 `--phase prd` 在无 prd 条目的项目上注入的**就是 cross-phase 那批**
+ *   （实测与 `--phase cross-phase` 输出只差表头一行）。本版**保持该语义**（改语义会破坏既有调用点），
+ *   改为用**阶段匹配度次级键**让真正属于本阶段的条目优先。
+ * - **排序补次级键**：原实现仅 `severityRank` 单键，同级顺序取决于 INDEX 行序；
+ *   新增"本阶段优先"与"date 降序"两级，使新增条目不再被旧条目永久压制。
+ * - **`--limit` / `--all`**：原硬编码 top-5（emp-auth 的 cross-phase 恰好 5 条 ⇒ **已满载**，
+ *   下一条除非 severity 更高否则永不可达）。调用方 MUST 显式传值——只加参数而不改调用点等于没改。
+ * - **列解析**：改用共享层 `parseTableRow`（原 `filter(Boolean)` 丢空列且仅下界守卫）。
+ * - **索引缺失由静默改为 WARN**：原输出一行 HTML 注释并以 0 退出，无人可见。
+ *
+ * v0.57.0 P4 修复（评审轮 M2/M3）：
+ * - **同源聚类补实现**（上条提到的病因在此收口）：`source` 相同的条目折叠为 1 条 + 标注
+ *   同源条数。仅作用于展示，**不合并条目内容**（与 D1-B 一致，见下方聚类段注释）。
+ * - **列数改为区间校验 + `file` 列语义校验**：`source` 列新增后 7/8 列都合法；
+ *   另加 `ENTRY_FILE_RE` 兜住"列数在界内但已错位"（summary 含未转义 `|` 的存量坏行）。
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { severityRank } from './severity.mjs';
+import { parseTableRow } from './md-normalize.mjs';
+
+/**
+ * INDEX 表列数范围（date | phase | domain | type | severity | summary | file [| source]）。
+ * v0.57.0 P4：`source` 列是本版新增 ⇒ 7（存量 INDEX）与 8（本版重建）都要接受。
+ */
+const INDEX_COLUMNS_MIN = 7;
+const INDEX_COLUMNS_MAX = 8;
+/** `file` 列的形状（`<phase>/<name>.md`）——语义校验，见下方列解析注释 */
+const ENTRY_FILE_RE = /^[a-z][a-z-]*\/.+\.md$/;
+/** 默认展示条数 */
+const DEFAULT_LIMIT = 5;
 
 export function run(args = {}) {
   const phase = args.phase || 'cross-phase';
   const domain = args.domain || '';
   const dir = args.dir || 'docs/solutions';
+  const all = args.all === true || args.all === 'true';
+  const rawLimit = Number(args.limit);
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : DEFAULT_LIMIT;
   const indexPath = join(dir, 'INDEX.md');
 
   if (!existsSync(indexPath)) {
-    console.log('<!-- No solutions index found, skipping injection -->');
+    console.warn(`⚠ 未找到 ${indexPath}，跳过复利注入（已捕获的经验不会出现在上下文中）`);
     return { entries: [] };
   }
 
   const content = readFileSync(indexPath, 'utf-8');
-  const lines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
-
   const entries = [];
-  for (const line of lines) {
-    const cols = line.split('|').map(c => c.trim()).filter(Boolean);
-    if (cols.length < 7) continue;
-    const [date, ePhase, eDomain, type, severity, summary, file] = cols;
 
-    // 过滤：phase 匹配或 cross-phase
+  for (const line of content.split('\n')) {
+    if (!line.startsWith('|') || line.startsWith('| date') || line.startsWith('|--')) continue;
+
+    const cells = parseTableRow(line);
+    // 上下界同时校验：只查下界无法发现"summary 含 `|` 导致列数变多、file 列错位"（v0.38.0 test-merge 同型缺陷）
+    if (cells.length < INDEX_COLUMNS_MIN || cells.length > INDEX_COLUMNS_MAX) continue;
+    const [date, ePhase, eDomain, type, severity, summary, file, source = ''] = cells;
+    // file 列语义校验（v0.57.0 P4）：列数在界内仍可能错位——例如 summary 含**未转义**的 `|`
+    // 时列数恰好落进 7/8 区间，摘要后半段会顶到 file 位。形状不符即丢弃，避免注入错位的路径。
+    if (!ENTRY_FILE_RE.test(file)) continue;
+
     const phaseMatch = ePhase === phase || ePhase === 'cross-phase';
-    // 过滤：domain 匹配（空 domain 表示通用）
     const domainMatch = !domain || !eDomain || eDomain === 'general' || eDomain === domain;
 
     if (phaseMatch && domainMatch) {
-      entries.push({ date, phase: ePhase, domain: eDomain, type, severity, summary, file });
+      entries.push({ date, phase: ePhase, domain: eDomain, type, severity, summary, file, source, isNative: ePhase === phase });
     }
   }
 
-  // 按 severity 降序排序，取 top-5
-  entries.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
-  const top5 = entries.slice(0, 5);
+  entries.sort((a, b) => {
+    const sevDiff = severityRank(a.severity) - severityRank(b.severity);
+    if (sevDiff !== 0) return sevDiff;
+    // 阶段匹配度：本阶段条目优先于通配的 cross-phase
+    if (a.isNative !== b.isNative) return a.isNative ? -1 : 1;
+    // 时间：新条目优先
+    return b.date.localeCompare(a.date);
+  });
+
+  // ── 同源聚类（v0.57.0 P4 补实现，设计 §4.1）──────────────────────────────
+  // D1-B 废止条目合并后，同一 change 产生的多条经验会各自成条——这是对的（内容零丢失），
+  // 但它们的 severity 与 date 通常相同 ⇒ 排序后**连续占满** top-N，把窗口的信息增益
+  // 压缩成"一个 change 的 N 条"。故折叠为 1 条并标注同源条数，把槽位还给其他经验。
+  // 为什么不合并条目本身：那正是 D1-B 废止的行为（实测丢 13 条内容）。折叠只作用于**展示**。
+  // `source` 为空（存量条目或手工条目）不参与聚类——没有可靠聚类键就不猜。
+  //
+  // ⚠ 已知假设：聚类键 `source` 是 **change 名**，故本实现假设"同一 change 的经验大多相关"
+  // （设计 §4.1 的动机是 v1-C3 的 5 个同源工具缺陷）。该假设对产出经验较杂的 change 不成立
+  // ——此时折叠会藏掉不相关信息。这是**有意的取舍**（窗口信息增益 vs 单条可达性），
+  // 且折叠只是展示层：条目仍在盘上、仍可被直接读取。若日后要收紧，正确的方向是引入
+  // 更细的聚类键（如事故 id），而不是关掉折叠。
+  const bySource = new Map();
+  const clustered = [];
+  for (const e of entries) {
+    if (!e.source) { clustered.push(e); continue; }
+    const head = bySource.get(e.source);
+    if (head) { head.siblings++; continue; }
+    const node = { ...e, siblings: 0 };
+    bySource.set(e.source, node);
+    clustered.push(node);
+  }
+  const foldedCount = entries.length - clustered.length;
+
+  const shown = all ? clustered : clustered.slice(0, limit);
 
-  if (top5.length === 0) {
-    console.log('<!-- No matching solutions found -->');
+  if (shown.length === 0) {
+    console.log(`<!-- No matching solutions found (phase=${phase}, domain=${domain || 'any'}) -->`);
     return { entries: [] };
   }
 
-  console.log(`## Solutions Context (phase=${phase}, domain=${domain || 'any'})`);
+  const foldedNote = foldedCount > 0 ? `, ${foldedCount} 条同源已折叠` : '';
+  console.log(`## Solutions Context (phase=${phase}, domain=${domain || 'any'}, showing ${shown.length}/${clustered.length}${foldedNote})`);
   console.log('');
-  for (const e of top5) {
+  for (const e of shown) {
     console.log(`- [${e.severity}] ${e.summary} (${e.phase}/${e.domain}, ${e.date}) → ${e.file}`);
+    if (e.siblings > 0) {
+      console.log(`  ↳ 另有 ${e.siblings} 条同源经验（source=${e.source}）已折叠；需要时按 file 直接读取`);
+    }
   }
   console.log('');
 
-  return { entries: top5 };
+  const hidden = clustered.length - shown.length;
+  if (hidden > 0) {
+    console.log(`<!-- 另有 ${hidden} 条匹配经验未展开：调大 --limit 或使用 --all -->`);
+    console.log('');
+  }
+
+  return { entries: shown, total: clustered.length, folded: foldedCount, hidden };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = {};
   for (let i = 2; i < process.argv.length; i += 2) {
     const key = process.argv[i]?.replace('--', '');
+    if (key === 'all') { args.all = true; i -= 1; continue; }
     const val = process.argv[i + 1];
     if (key && val) args[key] = val;
   }