@xulthekl/team-flow 0.56.1 → 0.58.0

package/scripts/lib/solutions-promote.mjs

@@ -7,53 +7,55 @@
  *
  * 功能：
  * 1. 读取 change 根 learnings.md（v0.49.0 §83.3.5：统一路径——此前注释误写 specs/<cap>/，
- *    与本文件第 58 行的实际实现及 compound-captured guard 均不一致）
- * 2. 逐条检查晋升条件（severity ≥ medium 且 type = pitfall/pattern）
- * 3. 检查与全局 INDEX 是否重复（domain+type 匹配）
- * 4. 符合条件 → 写入全局 docs/solutions/
- * 5. 重复 → 更新已有条目的 severity 和确认次数
+ *    与本文件的实际实现及 compound-captured guard 均不一致）
+ * 2. 逐条检查晋升条件（severity ≥ medium 且 type = pitfall/pattern，phase 须在合法枚举内）
+ * 3. **幂等判据 = 文件名 + 正文签名**（`<date>-<slug>.md` + `entryBodySignature`）：
+ *    两者都相同才是"同一条经验"——同标题不同正文是**两条**独立经验（见下方 P4 修复说明）
+ * 4. 文件不存在 → 新建条目；签名匹配 → 登记来源 change 并按其升级 severity（**不改内容**）
+ * 5. INDEX 由 `refreshIndex()` 派生（本脚本不直接写 INDEX）
  *
  * 变更说明（v0.5 / 2026-07-21）：
  * - 修正原稿在同步 run() 内使用 `await import('node:fs')` 取 mkdirSync 导致的语法错误，
  *   改为在顶部静态 import mkdirSync，保持与其它 solutions-* 脚本一致的同步签名。
+ *
+ * v0.57.0 §4.2/§4.4 重构（设计文档 compound-lifecycle-governance-design v2.2）：
+ * - **废止 `domain+type` 判重合并**（D1-B）：旧实现命中同 domain+type 即"合并"，只把
+ *   `confirmed` 计数 +1 而**正文丢弃**（emp-auth 实测 13 条内容丢失，仅存于 change 的 learnings.md）。
+ *   新实现每条经验独立成条 ⇒ 内容零丢失；跨 change 的"复发"信号改由 `confirmations`
+ *   来源集合承载，并据此升级 severity（每新增一个来源 change 升一档，重跑不升）。
+ * - **severity 与 confirmations 落条目文件 frontmatter**（唯一不被 INDEX 重建抹掉的持久层）。
+ *   旧实现把升级只写在 INDEX 行里 ⇒ index-gen 重建会把 `critical` 打回 `high`（实测 3/20 条）。
+ * - **新增 phase 白名单校验**与 capture 对齐，防止写入不可被索引的目录。
+ *
+ * v0.57.0 P4 修复（评审轮 C1/M1，隔离复现证实）：
+ * - **身份键塌缩丢条**：`cleanTitle` 剥离序号后，`## 3. 契约漂移` 与 `## 7. 契约漂移`
+ *   产出同一 slug ⇒ 同一文件名 ⇒ 第二条被判为"已登记"而**直接 continue**，
+ *   其**正文与 severity 整条消失**（无 WARN、不计 skipped、INDEX 无行）。这是本版
+ *   新引入的回归——cleanTitle 之前 slug 含序号（`3-契约漂移`），不会碰撞。
+ *   跨 change 同样中招（同日同标题 ⇒ 只回写 frontmatter、第二个 change 的正文被丢弃）。
+ *   修法：文件名降为身份的**标题分量**，另加 `entryBodySignature` 作**内容分量**，
+ *   碰撞时探测 `-2`/`-3` 后缀，签名匹配才算同一条 —— 与 D1-B「每条独立成条、内容零丢失」对齐。
+ *   两个分量的清洗口径必须**相反**：标题分量**要**清洗（序号是 change 局部编号，
+ *   不清洗则跨 change 复发永远匹配不上），内容分量**不能**清洗（清洗会抹掉同标题经验的区分度）。
  */
 
-import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { meetsMinSeverity, nextSeverity } from './severity.mjs';
-import { normalizeInline } from './md-normalize.mjs';
 import { slugify } from './slug.mjs';
+import { SOLUTION_PHASES } from './solutions-phases.mjs';
+import { refreshIndex } from './solutions-index-gen.mjs';
+// 条目身份（文件名 + 正文签名）、碰撞定位、frontmatter 读取——与 capture/index-gen 共用的**共享层**
+// （v0.57.0 P4；二轮评审把 frontmatter 读取也收敛进来：原先三处各有一份，只有本文件剥行尾注释）
+import {
+  entryBodySignature, resolveEntryPath, MAX_COLLISION_SUFFIX,
+  stripInlineComment, parseFrontmatter,
+} from './solutions-entry.mjs';
 
 /** 文件名 slug 截断长度（与 solutions-capture 一致） */
 const SLUG_MAX_LENGTH = 40;
 
-/**
- * 剥离 YAML 行尾注释（空格 + `#` 起始）——v0.23 §91 硬化：
- * templates/learnings.md 的取值说明写在行尾注释里，若被逐字复制进 learnings.md，
- * 注释会随取值一起进入 frontmatter，导致 severity 被判为未知值而静默不晋升。
- */
-function stripInlineComment(raw) {
-  return raw.replace(/\s+#.*$/, '').trim();
-}
-
-function parseFrontmatter(content) {
-  // learnings.md 中每个条目以 `## 标题` 开头，frontmatter 紧跟标题行之后；
-  // 故此处兼容 frontmatter 位于段首或标题行之后两种位置（^--- 只能匹配段首会漏判）。
-  const match = content.match(/(?:^|\n)---\n([\s\S]*?)\n---/);
-  if (!match) return null;
-  const fm = {};
-  for (const line of match[1].split('\n')) {
-    // v0.55.0 §8.4.3 横展（FB-4）：容忍全角冒号、`**key**` 加粗与反引号
-    // （走共享层 `normalizeInline`）。原实现只认半角 `:` + 裸键名，
-    // `severity：high` / `**severity**: high` 会整键丢失 → 该条静默不晋升。
-    const idx = line.search(/[:：]/);
-    if (idx > 0) {
-      fm[normalizeInline(line.slice(0, idx))] = normalizeInline(stripInlineComment(line.slice(idx + 1)));
-    }
-  }
-  return fm;
-}
 
 function parseLearnings(content) {
   // 解析 learnings.md 中的经验条目（## 标题分隔）
@@ -61,7 +63,10 @@ function parseLearnings(content) {
   return sections.map(s => {
     const lines = s.trim().split('\n');
     const title = lines[0]?.trim() || '';
-    const fm = parseFrontmatter(s);
+    // 剔掉 `## 标题` 行（及随后的空行），使条目 frontmatter 落回**段首** ——
+    // 共享层的 `parseFrontmatter` 严格锚定段首，故不能用"容忍中置"换取方便：
+    // 那会让正文里的水平线 / 围栏样例也被当成元数据（v0.57.0 四轮实测的幽灵条目缺陷）。
+    const fm = parseFrontmatter(s.replace(/^[^\n]*\n/, '').trimStart());
     return { title, fm, body: s.trim() };
   // v0.49.0 §83.3.5：排除文件级标题（`# Session Learnings` 会被 split 成首个 section），
   // 否则它会被当成一条无 frontmatter 的条目计入 skipped
@@ -82,41 +87,65 @@ function renderEntryBody(learning) {
 }
 
 /**
- * v0.49.0 §83.3.5：重复命中时按 promotion-rules.md 承诺真正落盘（原实现只 `updated++`，
- * 不更新 INDEX 行、不标记条目）——升级 INDEX 行 severity + 条目文件 confirmed 计数。
+ * 清洗 learnings 标题中的序号前缀（`8. 改 tasks.md 文本…` → `改 tasks.md 文本…`）。
+ *
+ * v0.57.0：`title` 是**检索字段 + 文件名来源 + INDEX 摘要**三处复用（§4.1），
+ * 而 learnings.md 的 `## N. <标题>` 序号只在该文件内有意义，带出去会污染三处。
  */
-function confirmExistingEntry(solutionsDir, indexContent, domain, type) {
-  const lines = indexContent.split('\n');
-  for (let i = 0; i < lines.length; i += 1) {
-    // INDEX 列：| date | phase | domain | type | severity | summary | file |
-    const cols = lines[i].split('|').map(column => column.trim());
-    if (cols.length < 9 || cols[3] !== domain || cols[4] !== type) continue;
-
-    const currentSeverity = cols[5];
-    const upgraded = nextSeverity(currentSeverity);
-    if (upgraded !== currentSeverity) {
-      lines[i] = lines[i].replace(`| ${currentSeverity} |`, `| ${upgraded} |`);
-    }
-    markEntryConfirmed(join(solutionsDir, cols[7]));
-    return { indexContent: lines.join('\n'), from: currentSeverity, to: upgraded, file: cols[7] };
-  }
-  return null;
+function cleanTitle(raw) {
+  return String(raw ?? '').replace(/^\d+[.、]\s*/, '').trim();
 }
 
-function markEntryConfirmed(filePath) {
-  if (!existsSync(filePath)) return;
+/** 解析 frontmatter 中的 `confirmations: [a, b]`（内联数组；容错缺失与加粗） */
+function parseConfirmations(fmBlock) {
+  const m = fmBlock.match(/^\**confirmations\**\s*[:：]\s*\[([^\]]*)\]\s*$/m);
+  if (!m) return [];
+  return m[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+}
+
+/** 读写 frontmatter 标量键（容错全角冒号与 `**key**` 加粗，沿用 FB-4 的容忍面） */
+function readScalar(fmBlock, key) {
+  const m = fmBlock.match(new RegExp(`^\\**${key}\\**\\s*[:：]\\s*(.+?)\\s*$`, 'm'));
+  // 剥行尾注释（v0.57.0 P4）：手工条目常写 `severity: high   # 说明`。不剥则 nextSeverity
+  // 收到未知值原样返回 ⇒ 该条 severity **永不升级且无任何提示**（实测 "high # 说明" → "high # 说明"）。
+  return m ? stripInlineComment(m[1]) : null;
+}
+
+function writeScalar(fmBlock, key, value) {
+  const re = new RegExp(`^\\**${key}\\**\\s*[:：].*$`, 'm');
+  if (re.test(fmBlock)) return fmBlock.replace(re, `${key}: ${value}`);
+  return `${fmBlock}\n${key}: ${value}`;
+}
+
+/**
+ * v0.57.0 §4.2/§4.4：确认既有条目 —— **只改条目文件，不写 INDEX**。
+ *
+ * 语义（与旧实现的三处差异）：
+ * - 旧：命中 `domain+type` 即"合并"，只把 `confirmed` 计数 +1（内容丢失，见设计文档 P-1）
+ * - 新：**不合并内容**（D1-B 每条独立成条），确认动作仅登记"来源 change"并按其升级 severity
+ * - 幂等：同一 change 重复 promote 时**不升 severity**（那是重跑，不是新证据）；
+ *   只有**新出现的来源 change** 才升一档 —— 对应 §4.4 的"每新增一个来源 change 升一档"
+ * - 落点：severity 与 confirmations **都落条目文件 frontmatter**（唯一不被 INDEX 重建抹掉的持久层）
+ */
+function confirmByFile(filePath, changeName) {
   const content = readFileSync(filePath, 'utf-8');
   const block = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!block) return;
-  // v0.55.0 §8.4.3 横展（FB-4）：容忍全角冒号与 `**confirmed**` 加粗。
-  // 放宽前这类行匹配不到 → 走追加分支 → frontmatter 出现**重复 confirmed 键**
-  // （计数错乱且静默）。命中后统一改回规范形态 `confirmed: N`。
-  const counter = block[1].match(/^\**confirmed\**\s*[:：]\s*(\d+)\s*$/m);
-  const next = counter ? parseInt(counter[1], 10) + 1 : 2;
-  const frontmatter = counter
-    ? block[1].replace(/^\**confirmed\**\s*[:：]\s*\d+\s*$/m, `confirmed: ${next}`)
-    : `${block[1]}\nconfirmed: ${next}`;
-  writeFileSync(filePath, content.replace(block[0], `---\n${frontmatter}\n---`), 'utf-8');
+  if (!block) return null;
+
+  const fm = block[1];
+  const seen = parseConfirmations(fm);
+  const currentSeverity = readScalar(fm, 'severity') || 'medium';
+
+  if (seen.includes(changeName)) {
+    return { alreadyConfirmed: true, from: currentSeverity, to: currentSeverity, confirmations: seen };
+  }
+
+  const upgraded = nextSeverity(currentSeverity);
+  let next = writeScalar(fm, 'severity', upgraded);
+  next = writeScalar(next, 'confirmations', `[${[...seen, changeName].join(', ')}]`);
+  writeFileSync(filePath, content.replace(block[0], `---\n${next}\n---`), 'utf-8');
+
+  return { alreadyConfirmed: false, from: currentSeverity, to: upgraded, confirmations: [...seen, changeName] };
 }
 
 export function run(args = {}) {
@@ -142,15 +171,14 @@ export function run(args = {}) {
     return { promoted: 0, updated: 0, skipped: 0 };
   }
 
-  // 读取全局 INDEX
-  const indexPath = join(solutionsDir, 'INDEX.md');
-  let indexContent = existsSync(indexPath) ? readFileSync(indexPath, 'utf-8') : '';
-
   let promoted = 0;
   let updated = 0;
+  let unchanged = 0;
   // v0.49.0 §83.3.5：跳过原因可见化（原实现静默 continue，用户看不出为什么一条都没晋升）
   const skipped = [];
 
+  const changeName = basename(changeDir);
+
   for (const learning of learnings) {
     const severity = learning.fm?.severity || 'low';
     const type = learning.fm?.type || 'insight';
@@ -170,31 +198,54 @@ export function run(args = {}) {
       continue;
     }
 
-    // 检查重复：domain+type 匹配
-    const dupRegex = new RegExp(`\\| ${domain} \\| ${type} \\|`);
-    if (dupRegex.test(indexContent)) {
-      const outcome = confirmExistingEntry(solutionsDir, indexContent, domain, type);
-      if (!outcome) {
-        skipped.push({ title: learning.title, reason: `duplicate ${domain}/${type} 但 INDEX 行无法定位` });
-        continue;
-      }
-      indexContent = outcome.indexContent;
-      writeFileSync(indexPath, indexContent, 'utf-8');
-      console.log(`Confirmed: ${domain}/${type} severity ${outcome.from} → ${outcome.to}（${outcome.file}）`);
-      updated++;
+    // v0.57.0 §4.4：phase 白名单校验 —— capture 一直有校验，promote 此前**没有**。
+    // 实测 promote 接受 `phase: tools` 会建出 docs/solutions/tools/ 并追加 INDEX 行，
+    // 随后 index-gen 重建时该目录不被扫描 ⇒ 条目**静默从 INDEX 消失且不计入 dropped**。
+    if (!SOLUTION_PHASES.includes(phase)) {
+      skipped.push({
+        title: learning.title,
+        reason: `phase="${phase}" 不在合法枚举（${SOLUTION_PHASES.join(' | ')}）`,
+      });
       continue;
     }
 
-    // 写入全局
     const date = learning.fm?.date || new Date().toISOString().slice(0, 10);
+    // title 仅供检索/摘要/frontmatter 三处复用（§4.1），**不进身份键**——清洗会抹掉区分度
+    const title = cleanTitle(learning.title);
+    const slug = slugify(title, { maxLength: SLUG_MAX_LENGTH });
     const phaseDir = join(solutionsDir, phase);
-    if (!existsSync(phaseDir)) {
-      mkdirSync(phaseDir, { recursive: true });
+
+    // 正文标题也走清洗：签名基准须跨 change 可比（序号是 change 局部编号，见 entryBodySignature）
+    const entryBody = renderEntryBody({ ...learning, title });
+    const resolved = resolveEntryPath(phaseDir, date, slug, entryBodySignature(entryBody));
+    if (!resolved) {
+      skipped.push({
+        title: learning.title,
+        reason: `同标题条目已达上限 ${MAX_COLLISION_SUFFIX} 条，未写入：${phase}/${slug}-*.md`,
+      });
+      continue;
+    }
+    const { filePath, fileName, isNew } = resolved;
+
+    // 既有条目：登记来源 change（同 change 重跑 = 幂等不升档；新来源 = 升一档）
+    if (!isNew) {
+      const outcome = confirmByFile(filePath, changeName);
+      if (!outcome) {
+        skipped.push({ title: learning.title, reason: `既有条目缺 frontmatter，无法登记确认：${phase}/${fileName}` });
+        continue;
+      }
+      if (outcome.alreadyConfirmed) {
+        console.log(`Unchanged: ${phase}/${fileName}（${changeName} 已登记）`);
+        unchanged++;
+      } else {
+        console.log(`Confirmed: ${phase}/${fileName} severity ${outcome.from} → ${outcome.to}`);
+        updated++;
+      }
+      continue;
     }
 
-    const slug = slugify(learning.title, { maxLength: SLUG_MAX_LENGTH });
-    const fileName = `${date}-${slug}.md`;
-    const filePath = join(phaseDir, fileName);
+    // 新建条目
+    if (!existsSync(phaseDir)) mkdirSync(phaseDir, { recursive: true });
 
     const fileContent = `---
 phase: ${phase}
@@ -202,29 +253,30 @@ domain: ${domain}
 type: ${type}
 severity: ${severity}
 date: ${date}
-source: ${basename(changeDir)}
+source: ${changeName}
+title: ${title}
+confirmations: [${changeName}]
 ---
 
-${renderEntryBody(learning)}
+${entryBody}
 `;
     writeFileSync(filePath, fileContent, 'utf-8');
 
-    // 追加 INDEX
-    const indexRow = `| ${date} | ${phase} | ${domain} | ${type} | ${severity} | ${learning.title.slice(0, 80)} | ${phase}/${fileName} |\n`;
-    appendFileSync(indexPath, indexRow, 'utf-8');
-    indexContent += indexRow;
-
     console.log(`Promoted: ${phase}/${fileName}`);
     promoted++;
   }
 
+  // v0.57.0 §4.2：INDEX 由**共享入口**派生（promote 不再直接写 INDEX）。
+  // refreshIndex 在目录缺失时创建，故首次晋升的项目也能正常产出索引。
+  refreshIndex(solutionsDir, { quiet: true });
+
   // v0.49.0 §83.3.5：解析/晋升/确认/跳过汇总（原实现只报 promoted/updated）
-  console.log(`\nPromotion complete: ${promoted} promoted, ${updated} confirmed, ${skipped.length} skipped`);
+  console.log(`\nPromotion complete: ${promoted} promoted, ${updated} confirmed, ${unchanged} unchanged, ${skipped.length} skipped`);
   if (skipped.length > 0) {
     console.log('Skipped entries:');
     for (const item of skipped) console.log(`  - ${item.title}: ${item.reason}`);
   }
-  return { promoted, updated, skipped: skipped.length };
+  return { promoted, updated, unchanged, skipped: skipped.length };
 }
 
 if (process.env.NODE_ENV !== 'test' && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/scripts/lib/test-merge.mjs

@@ -28,6 +28,7 @@ import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync, readdirSync
 import { join, basename, relative, resolve } from 'node:path';
 import { execSync } from 'node:child_process';
 import { slugify } from './slug.mjs';
+import { parseTableRow } from './md-normalize.mjs';
 
 /**
  * 解析 CLI 参数数组为结构化对象
@@ -94,12 +95,26 @@ export function extractSummary(content) {
 }
 
 /**
- * 从 test-matrix.md 提取模块分段（## Cases 下的 ### 子段）
- * 返回 { moduleName: sectionContent } 映射
+ * test-matrix 中承载「测试模块」的 `## ` 段名白名单。
+ *
+ * v0.57.0 §4.3（设计文档 compound-lifecycle-governance-design v2.2）：
+ * 原实现的 docstring 写「## Cases 下的 ### 子段」，**实现却是全文扫描所有 `### `**，
+ * 于是附录/台账段（`### 执行结果（三仓实测…）`、`### case_id ↔ 测试方法逐条对账`、
+ * `### Task 5.x`、`### W6-1 / W6-2 收口`）也被当作模块生成 baseline——
+ * emp-auth 实测 C1 的 21 个 `###` 中 **12 个属此类**，文件仅 440–520B、无测试复用价值。
+ *
+ * 两条硬约束：
+ * - MUST 用**精确段名**比较——`## Adversarial Cases` 含子串 `Cases`，用 `includes` 会误判边界
+ * - `## E2E / AC Verification` 不可省——它是 v0.38.0 引入 E2E 层级时的遗漏；实测
+ *   `vrm4teamflow/changes/C2-policy-management` 的 `### AC1..AC8`（**32 个 AC/E2E 用例**）
+ *   位于该段下，只列 `## Cases` 会让这批台账**静默冻结**：落选文件不会从 INDEX 消失
+ *   （`rewriteIndex` 扫 baselines 目录），故既无报错也无计数变化
  */
-function extractModuleSections(content) {
+export const MODULE_SECTIONS = Object.freeze(['## Cases', '## E2E / AC Verification']);
+
+/** 扫描给定行范围内的 `### ` 子段（不判定边界，边界由调用方给定） */
+function scanModuleHeadings(lines) {
   const sections = {};
-  const lines = content.split('\n');
   let currentModule = null;
   let currentLines = [];
 
@@ -120,6 +135,45 @@ function extractModuleSections(content) {
   return sections;
 }
 
+/**
+ * 从 test-matrix.md 提取模块分段（**白名单段**下的 `### ` 子段）
+ * 返回 { moduleName: sectionContent } 映射
+ *
+ * @param {string} content
+ * @param {{sectionNames?: readonly string[], onWarn?: (msg: string) => void}} [options]
+ */
+export function extractModuleSections(content, { sectionNames = MODULE_SECTIONS, onWarn = null } = {}) {
+  const lines = content.split('\n');
+
+  // 定位各白名单段的区间：[起, 止)，止于下一个 `## ` 标题
+  const bounds = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!sectionNames.includes(lines[i].trim())) continue;
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (/^## /.test(lines[j])) { end = j; break; }
+    }
+    bounds.push([i + 1, end]);
+  }
+
+  if (bounds.length === 0) {
+    // 无白名单段 ⇒ 回退全文扫描并**显式告警**。
+    // 原实现的"静默空操作"（sections = {} → 打印 0 modules processed）不可接受：
+    // 那会让整类台账在无任何提示的情况下停止更新。
+    if (onWarn) {
+      onWarn(`test-matrix 未找到模块段（${sectionNames.join(' / ')}），已回退为扫描全文 ### 子段。`
+        + '若该文件的模块段命名不同，请补入 MODULE_SECTIONS。');
+    }
+    return scanModuleHeadings(lines);
+  }
+
+  const sections = {};
+  for (const [start, end] of bounds) {
+    Object.assign(sections, scanModuleHeadings(lines.slice(start, end)));
+  }
+  return sections;
+}
+
 /**
  * 从 test-matrix.md 提取 Candidate Coverage Ledger
  */
@@ -137,7 +191,9 @@ function extractCandidateLedger(content) {
       break;
     }
     if (inLedger && line.startsWith('|') && !line.match(/^\|\s*[-:]+/)) {
-      const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+      // v0.57.0 §4.4：改用共享层 `parseTableRow`（原 `filter(Boolean)` 丢空列 →
+      // 台账中任何一个空单元格都会让后续列左移，`decision`/`caseIds`/`reason` 全部错位）
+      const cells = parseTableRow(line);
       if (cells.length >= 3 && cells[0] !== 'candidate') {
         candidates.push({
           candidate: cells[0],
@@ -169,7 +225,8 @@ function extractDeferredItems(content) {
       break;
     }
     if (inDeferred && line.startsWith('|') && !line.match(/^\|\s*[-:]+/)) {
-      const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+      // v0.57.0 §4.4：同 `extractCandidateLedger`，改用共享层 `parseTableRow`
+      const cells = parseTableRow(line);
       if (cells.length >= 3 && cells[0] !== 'case_id') {
         items.push({
           caseId: cells[0],
@@ -200,7 +257,9 @@ function legacySlug(moduleName) {
  *
  * 故读取时双查找：新 slug 优先 → 旧 slug 回退 → 都不存在才按新规则新建。
  * 命中旧命名文件后**原地更新**（保持旧名，不强制改名）——批量改名属 P1 的
- * 稳定 `module_id` + `--rekey` 迁移范畴（见 `docs/plan/compound-lifecycle-governance-design.md` §4.3）。
+ * 稳定 `module_id` + `--rekey` 迁移范畴（见设计文档 compound-lifecycle-governance-design §4.5；
+ * 该文档位于 team-flow-workspace 工作区，**不随插件发布**，故此处不给路径避免死引用）；
+ * 该方案 v2.0 起已把「稳定 module_id」从 §4.3 移至 §4.5，§4.3 改为 test-matrix 模块边界）。
  */
 function resolveBaselinePath(baselinesDir, moduleName) {
   const next = join(baselinesDir, `${slugify(moduleName)}.md`);
@@ -274,7 +333,7 @@ export function createNewBaseline(moduleName, sectionContent, changeName, date,
     l.startsWith('|') && !l.match(/^\|\s*[-:]+/) && !l.match(/\|\s*case_id/)
   );
   for (const line of caseLines) {
-    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+    const cells = parseTableRow(line);
     if (cells.length >= 11) {
       lines.push(`| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[5]} | ${cells[6]} | ${cells[8]} | ${cells[9]} | ${cells[10]} | ${changeName} |`);
     }
@@ -317,7 +376,7 @@ export function mergeExistingBaseline(existing, sectionContent, changeName, date
   );
 
   const renderCaseRow = (line) => {
-    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+    const cells = parseTableRow(line);
     if (cells.length < 11) return null;
     return `| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[5]} | ${cells[6]} | ${cells[8]} | ${cells[9]} | ${cells[10]} | ${changeName} |`;
   };
@@ -390,7 +449,7 @@ export function resolveDeferred(ledgerDir, changeName, newCaseIds, dryRun) {
         continue;
       }
       if (inDeferred && line.startsWith('|') && !line.match(/^\|\s*[-:]/)) {
-        const cells = line.split('|').slice(1, -1).map(c => c.trim());
+        const cells = parseTableRow(line);
         if (cells.length && newCaseIds.includes(cells[0])) {
           changed = true;
           resolved++;
@@ -547,7 +606,9 @@ async function main(argv, projectRoot) {
 
   const matrixContent = preCheckResult.content;
   const summary = extractSummary(matrixContent);
-  const moduleSections = extractModuleSections(matrixContent);
+  const moduleSections = extractModuleSections(matrixContent, {
+    onWarn: msg => console.warn(`⚠ ${msg}`),
+  });
   const candidateLedger = extractCandidateLedger(matrixContent);
   const deferredItems = extractDeferredItems(matrixContent);
 
@@ -573,7 +634,7 @@ async function main(argv, projectRoot) {
     const lines = section.split('\n');
     for (const line of lines) {
       if (line.startsWith('|') && !line.match(/^\|\s*[-:]+/) && !line.match(/\|\s*case_id/)) {
-        const cells = line.split('|').slice(1, -1).map(c => c.trim());
+        const cells = parseTableRow(line);
         if (cells[0]) newCaseIds.push(cells[0]);
       }
     }

package/scripts/team-flow.mjs

@@ -128,12 +128,16 @@ Commands:
                         Read one allowlisted package asset for a skill
   solutions index-gen [--dir <solutions-dir>]
                         Rebuild docs/solutions/INDEX.md (v0.5 compound-learning)
-  solutions inject --phase <p> [--domain <d>] [--dir <solutions-dir>]
-                        Emit top-5 filtered solution summaries for skill context injection
+  solutions inject --phase <p> [--domain <d>] [--limit <n>|--all] [--dir <solutions-dir>]
+                        Emit filtered solution summaries for skill context injection
+                        (default: top 5; sorted by severity, then phase-match, then date desc)
   solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>" [--source <src>] [--dir <solutions-dir>]
-                        Capture one learning into docs/solutions/ + INDEX.md
+                        Capture one learning into docs/solutions/ (INDEX rebuilt via index-gen)
   solutions promote <change-dir> [--dir <solutions-dir>]
                         Promote qualifying change learnings into global docs/solutions/
+                        (idempotent by file name; writes severity + confirmations to the entry file)
+  solutions backfill [--dry-run] [--dir <solutions-dir>]
+                        Add missing title: field to existing entries (v0.57.0; needed by learnings-researcher)
   install-cursor        Deploy skills/scripts/docs to .cursor/ (local Cursor setup)
   install-workbuddy     Deploy skills to WorkBuddy marketplace and enable them
   install-cline         Deploy to .cline/ + .clinerules/ (Cline)

package/skills/architecture-design/SKILL.md

@@ -207,8 +207,8 @@ architecture-design 执行时的上下文组装：
 4. 注入为架构决策约束（advisory 级）
 
 **架构复利注入（v0.36.3，复利链路修复）**：
-1. 执行 `tf solutions inject --phase architecture`（失败静默）——注入 `docs/solutions/` 中 phase=architecture 的历史架构决策经验（BC 边界取舍/聚合划分理由/事件投影设计踩坑）
-2. 读取失败 / 无条目 → 静默跳过，不阻断（advisory 级，与 S1 复利注入同语义）
+1. 执行 `tf solutions inject --phase architecture --limit 15`（失败不阻断：无索引时 CLI 输出一行 WARN 并返回空结果）——注入 `docs/solutions/` 中 phase=architecture 的历史架构决策经验（BC 边界取舍/聚合划分理由/事件投影设计踩坑）
+2. 读取失败 / 无条目 → 跳过、不阻断（advisory 级，与 S1 复利注入同语义；**无索引时 CLI 会输出一行 WARN 并返回空结果，那不是错误**）
 
 **始终加载**（**Fast Path 除外**——见上文 `### Fast Path`，该路径不读 `docs/architecture/` 下任何文件）：
 1. `Read docs/architecture/INDEX.md`（~50行摘要）

package/skills/architecture-design/references/s3.5-product-architecture.md

@@ -57,7 +57,7 @@
 
 - **触发场景**：BC 边界取舍、聚合划分理由、事件/读模型投影设计模式、技术选型决策、逆向重建低置信度修正
 - **命令**：`tf solutions capture --phase architecture --domain <触及BC> --type pitfall|pattern --severity medium --summary "<经验>"`（source: `iterations/vN/architecture.md`）
-- **注入端**：后续架构设计（变更级/产品级）执行时 `tf solutions inject --phase architecture` 自动注入这些经验（architecture-design 加载协议，v0.36.3）
+- **注入端**：后续架构设计（变更级/产品级）执行时 `tf solutions inject --phase architecture --limit 15` 自动注入这些经验（architecture-design 加载协议，v0.36.3；`--limit` v0.57.0 补）
 - **晋升说明**：产品级架构经验直接 capture 写 `docs/solutions/`（不走 change 级 promote——promote 只认 `learnings.md`，是变更级机制）
 
 ## 正向设计 vs 逆向重建

package/skills/architecture-design/templates/conventions/frontend-patterns.md

@@ -10,6 +10,13 @@ date: 2026-07-31
 > 本文件由 team-flow 被动式自动沉淀机制维护（v0.11 §33）。
 > 请勿手动编辑模板——此文件作为参考模板，实际项目规范在 `.team-flow/conventions/frontend-patterns.md` 中维护。
 
+## 魔法值（v0.58.0）
+
+- **数值 / 字符串字面量 MUST NOT 散落在模板与脚本中**——收敛到 `src/constants/` 下的常量模块，或组件内具名常量。
+- 判据归属：`clean-code` skill 的「魔法值（前端）」判据，分级 **Critical**（与后端「不允许魔法常量」对齐；此前前端无任何等价约束）。
+- 可豁免：结构性索引（如 `arr[0]`）、CSS 取值、仅出现一次且语义自明的字面量。
+- 背景：v1 实测中前端因无约束，同一 change 内出现 21 处硬编码业务码与状态值，被审查降级为 Minor。
+
 ## 框架选型
 - （项目级规范在此补充，如：Vue 2 Options API）
 

package/skills/build-executor/SKILL.md

@@ -11,7 +11,11 @@ Controls the implementation phase. Uses `execution-contract.md` as the workflow
 
 Read: `execution-contract.md`, `tasks.md`, relevant `specs/`, relevant `design.md`. (Skip contract/spec requirements when workflow is `tweak`.)
 
-**复利经验注入（v0.49.0 §83.3.5）**：运行 `tf solutions inject --phase cross-phase`（失败静默）——注入 `docs/solutions/` 中跨阶段可复用的历史经验（踩坑/模式），供实施时规避已知问题。注入内容是**经验提示而非约束**：与当前 change 的契约/规格冲突时以契约/规格为准，并把冲突回报给 workflow-start。
+**复利经验注入（v0.49.0 §83.3.5；v0.57.0 §4.1 调整 phase 取值与窗口）**：运行 `tf solutions inject --phase build --limit 15`（失败不阻断：无索引时 CLI 输出一行 WARN 并返回空结果，继续即可）——注入 `docs/solutions/` 中构建阶段与跨阶段的历史经验（踩坑/模式），供实施时规避已知问题。注入内容是**经验提示而非约束**：与当前 change 的契约/规格冲突时以契约/规格为准，并把冲突回报给 workflow-start。
+
+> **为什么必须显式传 `--limit`**：默认 top-5 在 cross-phase 条目已达 5 条时**满载**，本阶段新增条目（低 severity）永不可达——`--limit` 才是那个杠杆。换 `--phase` 取值**不是**杠杆：cross-phase 是通配符，当库内无本阶段条目时两者注入的**就是同一批**，跑两次只会让同一批经验在上下文中出现两遍。
+> **为什么取 15**：3× 默认窗口，够容纳"cross-phase 满载 + 若干本阶段新增"的典型情形；不取 `--all` 是因它无上界，与上下文预算口径（AGENTS.md 的 ~6.5k token）冲突。**调小前须确认本阶段新增条目不会被重新挤掉**——这正是本参数的设立原因。
+> 排序为 severity 降序 → 阶段匹配度（本阶段优先于通配）→ date 降序；同源条目（同 `source`，即同一 change 来源）折叠为 1 条并标注条数。折叠是**展示策略**，条目本身仍在盘上。
 
 When `architecture/sql/` exists, also read:
 - `architecture/sql/ddl/*.sql` — executable DDL scripts; reference directly for DB schema change tasks instead of hand-writing DDL
@@ -68,6 +72,8 @@ RED (write test, see it fail) → GREEN (write minimal code, see it pass) → RE
 ### Law 3: Review Before Drift
 Block on: logic defects, spec violations, missing required tests, unintended scope expansion.
 
+**Structural criteria（clean-code，v0.58.0）**：魔法值（未命名字面量）= Critical；函数长度 / 嵌套深度 / 参数个数 / 命名形式 = Minor；单一职责与 DRY 为审查必答项（无阈值）。**执行处是三个派发模板**（`implementer-prompt.md` / `task-reviewer-prompt.md` / `code-reviewer-prompt.md`）——它们各自内联了完整判据，因为由模板派发的子代理读不到 skill。本摘要仅供编排参考；判据真相源见 `clean-code` skill。
+
 ### Law 4: Rewind on Contract Break
 Return to `specifying` or `bridging` if: new behavior appears, interfaces change materially, design assumptions fail, artifacts no longer define intended implementation.
 

package/skills/build-executor/implementer-prompt.md

@@ -130,6 +130,25 @@ Subagent (general-purpose):
     - Are names clear and accurate (match what things do, not how they work)?
     - Is the code clean and maintainable?
 
+    **Structural criteria** — apply to every function this change adds or modifies:
+
+    - **Magic values** (unnamed numeric/string literals): name them as constants or enums.
+      This is **Critical** — do not ship unnamed literals. Applies to front-end code too.
+    - **Function length** >20 lines, **nesting depth** >2 levels, parameters >3,
+      **naming form** (constants SCREAMING_SNAKE; booleans `is`/`has`/`can` prefix):
+      Minor. When counting nesting, exclude try/catch's own level and guard-clause
+      `return`/`continue` levels; framework-fixed signatures are exempt from the
+      parameter rule.
+    - **Single responsibility**: can the function name cover ALL steps in the body?
+      If not, split it — or state in your report which steps it cannot cover.
+    - **DRY**: is there a structurally equivalent logic block elsewhere in THIS repository
+      (ignore comments, whitespace, identifier names)? If the duplicate lives in the same
+      shared publish unit (same package / module / directory), extract a shared layer
+      rather than copying — if you judge copying is right, say why in your report.
+    - **Pre-existing code**: these criteria apply only to what this change touches. A hit
+      inside a function that already existed is Minor — register it in your report as
+      `存量待整改` rather than restructuring outside your task scope.
+
     **Discipline:**
     - Did I avoid overbuilding (YAGNI)?
     - Did I only build what was requested?