@xulthekl/team-flow 0.56.1 → 0.58.0

package/docs/solutions/INDEX.md

@@ -1,4 +1,4 @@
 # Solutions Index
-<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
-| date | phase | domain | type | severity | summary | file |
-|------|-------|--------|------|----------|---------|------|
+<!-- 每条一行，排序 severity 降序 → date 降序 → file 兜底，≤150 条上限；summary/source 内的 | 转义为 \| -->
+| date | phase | domain | type | severity | summary | file | source |
+|------|-------|--------|------|----------|---------|------|--------|

package/docs/usage-guide.md

@@ -1,6 +1,6 @@
 # team-flow 使用说明（研发团队版）
 
-> 版本锚点：v0.50.0（26 skills + 17 agents）· 更新日期：2026-09-09
+> 版本锚点：v0.58.0（27 skills + 17 agents）· 更新日期：2026-09-12
 > 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
 > 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
 
@@ -239,7 +239,7 @@ tf arch-merge（架构增量 → docs/architecture/ 全局当前态）
   → tf deisolate --merge（worktree 代码合并回主分支，Step 5c Code Landing）
 ```
 
-这就是"改动不烂尾、知识不流失"的机制保障。经验沉淀后，下一个 change 的对应阶段会通过 `tf solutions inject` 自动注入 top-5 相关经验。
+这就是"改动不烂尾、知识不流失"的机制保障。经验沉淀后，下一个 change 的对应阶段会通过 `tf solutions inject` 自动注入相关经验（默认 top-5；调用点须显式传 `--limit`，否则 cross-phase 条目满载时本阶段新增条目永不可达）。
 
 ---
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.56.1",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 27 skills, one install.",
+  "version": "0.58.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.56.1: auto-sync CLI version with plugin version
+# v0.58.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.56.1"
+PLUGIN_VERSION="0.58.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.56.1.
+Current version: v0.58.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.56.1",
-  "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
+  "version": "0.58.0",
+  "description": "Unified plugin (27 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.56.1",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding). 26 skills + 17 agents, one install.",
+  "version": "0.58.0",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding). 27 skills + 17 agents, one install.",
   "author": {
     "name": "LT"
   },

package/scripts/lib/cmd-doctor.mjs

@@ -7,6 +7,13 @@ import { PLATFORM_RUNTIME_INVENTORY } from './platform-runtime-inventory.mjs';
 import { readState, VALID_STATES } from './state-loader.mjs';
 // v0.22 §85：tasks_skipped 豁免判定复用 guard 侧唯一真相源，避免同一规则两处实现漂移。
 import { hasExplicitTasksSkip } from '../guard/checks/tasks-gate-exemptions.mjs';
+// v0.57.0 §4.4：复利库健康检查（漂移/截断/白名单外布局/未晋升）复用既有共享层
+import { parseTableRow } from './md-normalize.mjs';
+import { parseFrontmatter, MAX_INDEX_ENTRIES } from './solutions-index-gen.mjs';
+// 条目枚举与 index-gen **同源**——含判据（不一致会报出"重跑 index-gen 也消不掉"的告警）
+// 与防御（非普通文件不抛异常；本维度无逐维度隔离，抛出会中止整个 doctor）
+import { listSolutionEntries } from './solutions-entry.mjs';
+import { SOLUTION_PHASES } from './solutions-phases.mjs';
 
 const RUNTIME_SKILLS = new Set([
   'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
@@ -332,6 +339,137 @@ function checkArchState(root) {
   return { pass: warnings.length === 0, message: warnings.length ? warnings.join('; ') : 'arch-state/iterations 一致' };
 }
 
+/**
+ * v0.57.0 §4.4：复利库健康检查（设计文档 compound-lifecycle-governance-design v2.2 §5 P1#6）。
+ *
+ * 四个维度合并为一条 doctor 结论（doctor 每维度输出一行）：
+ * A. **INDEX ↔ 文件漂移** —— 注入只读 INDEX（`solutions-inject.mjs`），任何失配都会静默影响 top-5。
+ *    本项是 §4.2「文件是唯一真相源、INDEX 只做投影」的**防复发**手段。
+ * B. **条目数 / 截断** —— `refreshIndex` 收进 capture/promote 后，截断从"从未触发"变为
+ *    "过 150 即每次静默淘汰"，须有可见的临近预警。
+ * C. **白名单外目录与平铺文件** —— 不被 `SOLUTION_PHASES` 收录的目录（如 ce-compound 的
+ *    category 目录、`workflow-patterns/`）与直接放在 `docs/solutions/` 下的条目文件，
+ *    对 CLI 通道**永久不可见**（不入 INDEX、不可注入）。
+ * D. **未 promote 的 change** —— 有 `learnings.md` 但 solutions 中无任何条目引用它的 change
+ *    （emp-auth 实测：C1 有 2 条 critical 因旧 bug 从未晋升）。
+ *
+ * advisory：与 doctor 其余维度一致，不阻断。
+ */
+function checkSolutions(root) {
+  const solutionsDir = join(root, 'docs', 'solutions');
+  if (!existsSync(solutionsDir)) {
+    return { pass: true, message: '未使用复利库（docs/solutions/ 不存在）' };
+  }
+
+  const problems = [];
+
+  // 收集条目文件（限白名单 phase 目录）
+  const entryFiles = [];
+  for (const phase of SOLUTION_PHASES) {
+    // v0.57.0 P4 五/六轮：条目枚举走**共享层**——它同时保证 ①与 `index-gen` 同判据
+    //（判据不一致会报出"重跑 index-gen 也消不掉"的告警）②**非普通文件不抛异常**。
+    // 后者对本维度尤为关键：`checkSolutions` 内联在 `checks` 数组字面量中、**无逐维度隔离**，
+    // 一次抛出会中止**整个 doctor**（12 个维度全丢），而它本来只是 advisory 巡检。
+    for (const e of listSolutionEntries(join(solutionsDir, phase))) {
+      entryFiles.push({ phase, file: e.file, rel: e.rel, content: e.content });
+    }
+  }
+
+  // A. INDEX ↔ 文件漂移
+  const indexPath = join(solutionsDir, 'INDEX.md');
+  if (existsSync(indexPath)) {
+    const indexRows = new Map();
+    for (const line of readFileSync(indexPath, 'utf-8').split('\n')) {
+      if (!line.startsWith('|') || line.startsWith('| date') || line.startsWith('|--')) continue;
+      const cells = parseTableRow(line);
+      // v0.57.0 P4：`source` 列新增后列数为 7（存量 INDEX）或 8（本版重建）；
+      // 另校验 `file` 列形状——列数在界内仍可能因未转义的 `|` 而错位。
+      if (cells.length < 7 || cells.length > 8) continue;
+      if (!/^[a-z][a-z-]*\/.+\.md$/.test(cells[6])) continue;
+      indexRows.set(cells[6], { date: cells[0], phase: cells[1], domain: cells[2], type: cells[3], severity: cells[4] });
+    }
+
+    const drifts = [];
+    const FIELDS = ['date', 'phase', 'domain', 'type', 'severity'];
+    for (const [rel, row] of indexRows) {
+      const fp = join(solutionsDir, rel);
+      if (!existsSync(fp)) { drifts.push(`${rel}（INDEX 有行、文件缺失）`); continue; }
+      // 防御同 `listSolutionEntries`（v0.57.0 P4 收尾）：INDEX 行指向的路径可能是目录 /
+      // 断链 symlink / 无读权限 / **FIFO**。前三类让本维度抛异常，而 `checkSolutions`
+      // 内联在 `checks` 字面量中、**无逐维度隔离** ⇒ 会**中止整个 doctor**（12 维度全丢）；
+      // FIFO 更会让 `readFileSync` **阻塞挂死**（不是异常，try/catch 也挡不住）——故先 `statSync` 判类型。
+      // INDEX 由 index-gen 生成、只对可枚举的普通文件出行，故现实实例为 0；但兜底成本是几行。
+      let raw;
+      try {
+        if (!statSync(fp).isFile()) { drifts.push(`${rel}（INDEX 有行、但该路径不是普通文件）`); continue; }
+        raw = readFileSync(fp, 'utf-8');
+      } catch {
+        drifts.push(`${rel}（INDEX 有行、但无法读取）`); continue;
+      }
+      const fm = parseFrontmatter(raw);
+      if (!fm) { drifts.push(`${rel}（无 frontmatter）`); continue; }
+      for (const k of FIELDS) {
+        if (fm[k] && fm[k] !== row[k]) { drifts.push(`${rel} ${k}: INDEX=${row[k]} 文件=${fm[k]}`); break; }
+      }
+    }
+    for (const e of entryFiles) {
+      if (!indexRows.has(e.rel)) drifts.push(`${e.rel}（文件存在、INDEX 无行）`);
+    }
+    if (drifts.length > 0) {
+      problems.push(`${drifts.length} 处 INDEX/文件漂移（${drifts.slice(0, 3).join('；')}${drifts.length > 3 ? ' …' : ''}）→ 运行 tf solutions index-gen 重建`);
+    }
+  }
+
+  // B. 条目数 / 截断
+  const total = entryFiles.length;
+  if (total > MAX_INDEX_ENTRIES) {
+    problems.push(`条目数 ${total} 已超索引上限 ${MAX_INDEX_ENTRIES}，超出部分不被索引（详见 index-gen 的 dropped 提示）`);
+  } else if (total > Math.floor(MAX_INDEX_ENTRIES * 0.8)) {
+    problems.push(`条目数 ${total} 接近索引上限 ${MAX_INDEX_ENTRIES}（>80%）`);
+  }
+
+  // C. 白名单外目录与平铺文件
+  const strayDirs = readdirSync(solutionsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !SOLUTION_PHASES.includes(e.name))
+    .map(e => `${e.name}/`);
+  const strayFiles = readdirSync(solutionsDir, { withFileTypes: true })
+    .filter(e => e.isFile() && e.name.endsWith('.md') && e.name !== 'INDEX.md')
+    .map(e => e.name);
+  if (strayDirs.length > 0) {
+    problems.push(`非白名单目录 ${strayDirs.join(', ')}（不被索引：CLI 通道不可见）`);
+  }
+  if (strayFiles.length > 0) {
+    problems.push(`平铺条目文件 ${strayFiles.join(', ')}（须移入 phase 子目录才可被索引）`);
+  }
+
+  // D. 未 promote 的 change
+  const changesDir = join(root, 'changes');
+  if (existsSync(changesDir)) {
+    const referenced = new Set();
+    for (const e of entryFiles) {
+      const fm = parseFrontmatter(readFileSync(join(solutionsDir, e.rel), 'utf-8'));
+      if (!fm) continue;
+      if (fm.source) referenced.add(fm.source.trim());
+      const confirmations = fm.confirmations || '';
+      for (const c of confirmations.replace(/^\[|\]$/g, '').split(',')) {
+        if (c.trim()) referenced.add(c.trim());
+      }
+    }
+    const unpromoted = readdirSync(changesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && existsSync(join(changesDir, e.name, 'learnings.md')))
+      .map(e => e.name)
+      .filter(name => !referenced.has(name));
+    if (unpromoted.length > 0) {
+      problems.push(`${unpromoted.length} 个 change 有 learnings.md 但未被晋升（${unpromoted.slice(0, 3).join(', ')}${unpromoted.length > 3 ? ' …' : ''}）`);
+    }
+  }
+
+  return {
+    pass: problems.length === 0,
+    message: problems.length ? problems.join(' | ') : `${total} 条经验，索引与文件一致`,
+  };
+}
+
 export async function run(args) {
   const root = process.cwd();
   const config = loadConfig(root);
@@ -351,6 +489,7 @@ export async function run(args) {
     ['Change states', checkChangeStates(root)],
     ['Change test gates', checkChangeTestGates(root)],
   ['Arch state', checkArchState(root)],
+  ['Solutions', checkSolutions(root)],
   ];
 
   // Config check
@@ -379,4 +518,4 @@ export async function run(args) {
   }
 }
 
-export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs, checkChangeStates, checkChangeTestGates };
+export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs, checkChangeStates, checkChangeTestGates, checkSolutions };

package/scripts/lib/cmd-solutions.mjs

@@ -2,12 +2,12 @@
 //
 // 设计说明（v0.5 / 2026-07-21）：
 // - 与 checkpoint / handoff / execution 一致，采用「单 COMMANDS key + 内部子命令分发」模式。
-// - 4 个底层脚本 solutions-{index-gen,inject,capture,promote}.mjs 的 run(args) 接收「对象」参数，
+// - 底层脚本 solutions-{index-gen,inject,capture,promote,backfill}.mjs 的 run(args) 接收「对象」参数，
 //   而 CLI 入口传入的是「字符串数组」。本分发器用 parseArgs 把数组解析成各脚本需要的对象后再调用，
 //   完成 数组 → 对象 的桥接。
 import { parseArgs } from 'node:util';
 
-const USAGE = 'Usage: tf solutions <index-gen|inject|capture|promote> [options]';
+const USAGE = 'Usage: tf solutions <index-gen|inject|capture|promote|backfill> [options]';
 
 export async function run(args) {
   const { positionals, values } = parseArgs({
@@ -21,6 +21,10 @@ export async function run(args) {
       severity: { type: 'string' },
       summary: { type: 'string' },
       source: { type: 'string' },
+      // v0.57.0 §4.1：inject 的展示条数控制与 backfill 的预演
+      limit: { type: 'string' },
+      all: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
     },
   });
 
@@ -35,7 +39,7 @@ export async function run(args) {
 
   if (subcommand === 'inject') {
     const mod = await import('./solutions-inject.mjs');
-    mod.run({ phase: values.phase, domain: values.domain, dir: values.dir });
+    mod.run({ phase: values.phase, domain: values.domain, dir: values.dir, limit: values.limit, all: values.all });
     return;
   }
 
@@ -61,7 +65,13 @@ export async function run(args) {
     return;
   }
 
-  console.error(`Unknown solutions subcommand: ${subcommand}. Valid: index-gen, inject, capture, promote`);
+  if (subcommand === 'backfill') {
+    const mod = await import('./solutions-backfill.mjs');
+    mod.run({ dir: values.dir, 'dry-run': values['dry-run'] });
+    return;
+  }
+
+  console.error(`Unknown solutions subcommand: ${subcommand}. Valid: index-gen, inject, capture, promote, backfill`);
   process.exit(2);
 }
 

package/scripts/lib/md-normalize.mjs

@@ -106,3 +106,42 @@ export function parseTaskLine(line) {
   if (!m) return null;
   return { indent: m[1].length, checked: m[3].toLowerCase() === 'x', text: m[4] };
 }
+
+/**
+ * 解析 Markdown 表格行 → 单元格字符串数组（**保留空列**）。
+ *
+ * v0.57.0 §4.4 抽为共享层。背景：`solutions-inject.mjs` 此前用
+ * `split('|').map(c => c.trim()).filter(Boolean)` —— `filter(Boolean)` **会丢空列**，
+ * 而守卫只有下界（`cols.length < 7`）⇒ 某单元格内容含 `|` 时列数变多、**不被拦截**，
+ * `file` 列取到错误值（与 `test-merge.mjs` 在 v0.38.0 修过的同型缺陷一致，当时未横展）。
+ *
+ * 约定：
+ * - `split('|')` 对 `| a | b |` 产出 `['', ' a ', ' b ', '']`，故取 `slice(1, -1)` 去首尾空串
+ * - 支持 `\|` 转义（v0.57.0 P4）：生成侧 `escapeCell` 把内容里的 `|` 写成 `\|`，
+ *   此处先换占位符再切分，否则转义符形同虚设（`\|` 仍会被 `split` 切开）。
+ *   无 `\|` 时与裸 `split('|').slice(1,-1)` **逐格一致**（含行尾缺竖线的非良构行——
+ *   两者对 `| a | b | c` 都返回 2 格）。与**本模块替换掉的旧版 `filter(Boolean)` 实现**
+ *   的差异才是实质的：旧版无 `slice`、且 `filter(Boolean)` 丢空列 ⇒ 同样的
+ *   `| a | b | c` 返回 3 格、而 `| a |  | c |` 返回 2 格（空列消失导致后续列全部左移）
+ * - **不做**列数校验——期望列数由调用方决定（INDEX 为 7/8 列，test-matrix 为 12 列）
+ * - 调用方 MUST 同时校验**上界与下界**（只查下界无法发现"多出的 `|` 导致的错位"）
+ *
+ * ⚠ 同名函数差异矩阵（v0.57.0 P4 评审补充，避免按名字误挑）：
+ * | 位置 | 非法输入 | 清洗 |
+ * |---|---|---|
+ * | 本函数（md-normalize） | **永不返回 null**，非表格行也产出数组 | 仅 trim + 还原 `\|` |
+ * | `arch-parse.mjs` | 返回 `null` | strip 反引号与强调标记 |
+ * | `ds-parse.mjs` | 返回 `null` | 走 `normalizeInline` |
+ * 本函数是最"裸"的一层 —— 调用方须自行判断行是否合法（如 `startsWith('|')`）。
+ *
+ * @param {string} line
+ * @returns {string[]}
+ */
+export function parseTableRow(line) {
+  const PIPE = '\u0001'; // 控制字符占位：正常 markdown 内容不含
+  return String(line)
+    .replace(/\\\|/g, PIPE)
+    .split('|')
+    .slice(1, -1)
+    .map(cell => cell.trim().replaceAll(PIPE, '|'));
+}

package/scripts/lib/solutions-backfill.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * solutions-backfill — 为存量复利条目补写 `title:` 字段
+ *
+ * v0.57.0 §4.1（设计文档 compound-lifecycle-governance-design v2.2）
+ * 用法：tf solutions backfill [--dir <solutions-dir>] [--dry-run]
+ *
+ * 为什么需要：
+ * `ce-plan`/`ce-ideate` 的 `learnings-researcher` 子代理按
+ * `title:` / `tags:` / `module:` / `problem_type:` 四个字段 grep 检索
+ * （`skills/ce-plan/references/agents/learnings-researcher.md:77-80`），
+ * 而 CLI 通道（promote/capture）此前写入的 frontmatter 只有
+ * `phase/domain/type/severity/date/source` —— **四个模式一个都命中不了**。
+ * 实测：emp-auth 21 个条目文件中，这四个模式**各只命中 1 个**（那条 ce-compound 通道写的条目）。
+ *
+ * v0.57.0 起 promote/capture 会写 `title:`，但**只改写入模板等于没改**——
+ * 存量条目仍检索不到（这正是 P-1 自己批评过的"修 bug 未回填"，v0.48.0→v0.51.0 同型）。
+ * 本命令补齐存量。
+ *
+ * title 推导口径（与 `solutions-index-gen` 的 `extractSummary` 同源）：
+ * ① 正文中的 `## <标题>` 行（promote 写入的形态）
+ * ② 回退：首个非空且非 `#` 开头的行
+ * 两者均经 `cleanTitle` 去 learnings 的 `N. ` 序号前缀（该序号只在其源文件内有意义）。
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SOLUTION_PHASES } from './solutions-phases.mjs';
+import { refreshIndex } from './solutions-index-gen.mjs';
+import { listSolutionEntries } from './solutions-entry.mjs';
+
+/** 与 solutions-promote 的 cleanTitle 同口径：去 `N. ` / `N、` 序号前缀 */
+function cleanTitle(raw) {
+  return String(raw ?? '').replace(/^\d+[.、]\s*/, '').trim();
+}
+
+/** 从条目正文推导 title */
+export function deriveTitle(content) {
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+
+  const heading = body.match(/^##\s+(.+)$/m);
+  if (heading) return cleanTitle(heading[1]);
+
+  const line = body.split('\n').map(l => l.trim()).find(l => l && !l.startsWith('#'));
+  return line ? cleanTitle(line).slice(0, 80) : null;
+}
+
+export function run(args = {}) {
+  const dir = args.dir || 'docs/solutions';
+  const dryRun = args['dry-run'] === true || args['dry-run'] === 'true';
+
+  if (!existsSync(dir)) {
+    console.error(`Solutions directory not found: ${dir}`);
+    return { filled: 0, already: 0, skipped: 0 };
+  }
+
+  let filled = 0;
+  let already = 0;
+  const skipped = [];
+
+  for (const phase of SOLUTION_PHASES) {
+    // 条目枚举走**共享层**（与 index-gen / doctor 同源）：含条目判据与"非普通文件不抛异常"防御。
+    // 副作用（有意）：阶段目录下的**非条目文档**（README / 格式说明）不再出现在 skipped 里——
+    // 它们本就不是"待补 title 的条目"，列出来只是噪音。
+    //
+    // ⚠️ 但下方**刻意**不复用共享层的 `parseFrontmatter`：本脚本只做**键存在性检测**
+    // 与**整块替换**（需要带 `---` 的完整匹配），不读取任何 frontmatter 值，
+    // 故不涉及"行尾注释剥离"那一类静默错判（P4 二轮 N1）。若日后需要读值，请改走共享层。
+    for (const { file, filePath, content } of listSolutionEntries(join(dir, phase))) {
+      const block = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!block) {
+        skipped.push(`${phase}/${file}（无 frontmatter）`);
+        continue;
+      }
+      // 容忍全角冒号与加粗（沿用 FB-4 的容忍面）
+      if (/^\**title\**\s*[:：]/m.test(block[1])) {
+        already += 1;
+        continue;
+      }
+
+      const title = deriveTitle(content);
+      if (!title) {
+        skipped.push(`${phase}/${file}（无法推导标题）`);
+        continue;
+      }
+
+      if (!dryRun) {
+        writeFileSync(filePath, content.replace(block[0], `---\n${block[1]}\ntitle: ${title}\n---`), 'utf-8');
+      }
+      filled += 1;
+    }
+  }
+
+  // INDEX 由共享入口派生（title 会成为新的摘要来源）
+  if (!dryRun && filled > 0) refreshIndex(dir, { quiet: true });
+
+  console.log(
+    `Backfill${dryRun ? '（dry-run）' : ''}: ${filled} filled, ${already} already had title, ${skipped.length} skipped`,
+  );
+  if (skipped.length > 0) {
+    console.log('Skipped:');
+    for (const item of skipped) console.log(`  - ${item}`);
+  }
+
+  return { filled, already, skipped: skipped.length };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = {};
+  for (let i = 2; i < process.argv.length; i += 1) {
+    if (process.argv[i] === '--dry-run') { args['dry-run'] = true; continue; }
+    if (process.argv[i] === '--dir' && process.argv[i + 1]) { args.dir = process.argv[++i]; }
+  }
+  run(args);
+}

package/scripts/lib/solutions-capture.mjs

@@ -1,25 +1,35 @@
 #!/usr/bin/env node
 /**
- * solutions-capture — 写入一条经验到 INDEX.md + 对应目录
+ * solutions-capture — 写入一条经验到 docs/solutions/<phase>/ + 刷新 INDEX
  *
  * v0.5 复利贯穿机制脚本
  * 用法：tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>"
  *   --severity 合法取值：critical | high | medium | low（v0.23 §91.3.4 起校验，非法值报错退出）
  *
  * 功能：
- * 1. 在对应阶段目录下创建经验文件
- * 2. 在 INDEX.md 中追加一行摘要
- * 3. INDEX.md 超过 150 行时触发 index-gen 重建
+ * 1. 在对应阶段目录下创建经验文件（含 `title:` 字段，v0.57.0 起）
+ * 2. 调用共享入口 `refreshIndex()` 重建 INDEX.md（本脚本**不再直接写 INDEX**）
+ *
+ * v0.57.0 §4.2（设计文档 compound-lifecycle-governance-design v2.2）：
+ * - 原实现以 `appendFileSync` 追加 INDEX 行，且是"INDEX 首次创建"（含表头）的**唯一来源**。
+ *   将写入权收归 `refreshIndex` 后，由它统一负责首建与重建——否则 capture 路径写下的条目
+ *   在下次 promote 前不在 INDEX 中（注入不可见），且无人再负责首次建索引。
+ * - 新增 `title:` 字段：`learnings-researcher` 按 `title:`/`tags:`/`module:`/`problem_type:`
+ *   检索，而 CLI 条目此前只有 `phase/domain/type/...` ⇒ 实测 4 个模式在 21 条中**各只命中 1 条**。
+ * - 删除本地的容量自查（原按"150 行"打印提示，**口径有误**——上限实为 150 **条**，文件另含 4 行头部）
+ *   ——容量由 `refreshIndex` 统一处理并 WARN。
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { SEVERITY_VALUES, isSeverity } from './severity.mjs';
+import { SEVERITY_VALUES, isSeverity, severityRank } from './severity.mjs';
 import { SOLUTION_PHASES } from './solutions-phases.mjs';
 import { slugify } from './slug.mjs';
+import { refreshIndex } from './solutions-index-gen.mjs';
+// 条目身份与碰撞定位——与 promote 共用的**共享层**（v0.57.0 P4）
+import { entryBodySignature, resolveEntryPath, readFrontmatterValue, MAX_COLLISION_SUFFIX } from './solutions-entry.mjs';
 
-const MAX_INDEX_LINES = 150;
 const SLUG_MAX_LENGTH = 40;
 
 export function run(args = {}) {
@@ -60,6 +70,8 @@ export function run(args = {}) {
   const filePath = join(phaseDir, fileName);
 
   // 写经验文件
+  // `title` 须为单行（它是 INDEX 摘要与 `learnings-researcher` 的检索字段）
+  const title = String(summary).replace(/\s*\n\s*/g, ' ').trim();
   const content = `---
 phase: ${phase}
 domain: ${domain}
@@ -67,6 +79,7 @@ type: ${type}
 severity: ${severity}
 date: ${date}
 source: ${source}
+title: ${title}
 ---
 
 ## 问题描述
@@ -78,24 +91,58 @@ ${summary}
 ## 预防措施/应用方式
 （待补充）
 `;
-  writeFileSync(filePath, content, 'utf-8');
 
-  // 追加 INDEX.md
-  const indexPath = join(dir, 'INDEX.md');
-  if (!existsSync(indexPath)) {
-    writeFileSync(indexPath, '# Solutions Index\n<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->\n| date | phase | domain | type | severity | summary | file |\n|------|-------|--------|------|----------|---------|------|\n', 'utf-8');
+  // v0.57.0 P4：碰撞保护 —— 原实现无条件 `writeFileSync`，同日同 slug 会**静默覆盖**
+  // （丢正文、丢已升的 severity、丢 confirmations），使"内容零丢失"在本通道为假。
+  // 身份判据与 promote 共用共享层（`solutions-entry.mjs`），避免两条通道各写一份实现。
+  const resolved = resolveEntryPath(phaseDir, date, slug, entryBodySignature(content));
+  if (!resolved) {
+    console.error(`✗ 同标题条目已达上限 ${MAX_COLLISION_SUFFIX} 条，未写入：${phase}/${slug}-*.md`);
+    process.exit(1);
   }
-  appendFileSync(indexPath, `| ${date} | ${phase} | ${domain} | ${type} | ${severity} | ${summary.slice(0, 80)} | ${phase}/${fileName} |\n`, 'utf-8');
+  if (!resolved.isNew) {
+    // 签名相同 = 同一条经验（重复 capture）⇒ 幂等，不重复写入、不覆盖。
+    // 但 severity **只升不降**：两次 capture 的差异可能**全在 frontmatter**（正文同、severity 不同），
+    // 而签名刻意剔除 frontmatter ⇒ 若在此直接返回，用户"提高等级"的意图会被静默吞掉
+    // （v0.57.0 P4 实测：`severity: critical` 重复 capture 后条目仍是 `high`）。
+    const existing = readFileSync(resolved.filePath, 'utf-8');
+    // 读 severity 必须走共享层（**剥行尾注释**）——裸读会把 `high  # 注释` 当未知值，
+    // 使下面的"只升不降"判据把这次 `medium` 误判为升级，日志打 Upgraded 实为**降级**
+    const current = readFrontmatterValue(existing, 'severity') || '';
+    const rel = `${phase}/${resolved.fileName}`;
+
+    // ⚠ `severityRank` 是**越小越严重**（critical=0 … low=3，见 severity.mjs）。
+    // 注入/索引侧用它做升序排序（critical 排最前），故此处的"更严重"判据是 `<` 而非 `>`
+    // ——写反会让 critical 被判为降级、medium 被判为升级（v0.57.0 P4 实测踩过）。
+    if (!current) {
+      // 既有条目**没有 severity 行**（手工条目）：无从比较档位。
+      // 不能把 null 兜成 `''` 后去比较 —— `severityRank('')` 落未知值档（4），
+      // 任何合法 severity 都会被判为"升级"，于是**日志与返回值谎报升级而文件未变**
+      //（v0.57.0 P4 三轮实测：返回 `upgradedFrom: ""` 且文件无 severity 行）。
+      console.log(`Already captured: ${rel}（内容一致，未重复写入；既有条目无 severity 行，未比较档位）`);
+      return { file: rel, phase, domain, type, severity, alreadyExisted: true };
+    }
 
-  // 检查是否超过 150 行
-  const indexContent = readFileSync(indexPath, 'utf-8');
-  const dataLines = indexContent.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
-  if (dataLines.length > MAX_INDEX_LINES) {
-    console.log(`INDEX.md exceeded ${MAX_INDEX_LINES} lines, consider running: tf solutions index-gen`);
+    if (severityRank(severity) < severityRank(current)) {
+      writeFileSync(resolved.filePath, existing.replace(/^severity\s*:\s*.+$/m, `severity: ${severity}`), 'utf-8');
+      refreshIndex(dir, { quiet: true });
+      console.log(`Upgraded: ${rel} severity ${current} → ${severity}（同一条经验，只升不降）`);
+      return { file: rel, phase, domain, type, severity, alreadyExisted: true, upgradedFrom: current };
+    }
+
+    const downgradedNote = severityRank(severity) > severityRank(current)
+      ? `；本次 ${severity} 低于既有 ${current}，按"只升不降"忽略`
+      : '';
+    console.log(`Already captured: ${rel}（内容一致，未重复写入${downgradedNote}）`);
+    return { file: rel, phase, domain, type, severity, alreadyExisted: true };
   }
+  writeFileSync(resolved.filePath, content, 'utf-8');
+
+  // v0.57.0 §4.2：INDEX 由共享入口派生（capture 不再直接写 INDEX）
+  refreshIndex(dir, { quiet: true });
 
-  console.log(`Captured: ${phase}/${fileName} (${severity}/${type})`);
-  return { file: `${phase}/${fileName}`, phase, domain, type, severity };
+  console.log(`Captured: ${phase}/${resolved.fileName} (${severity}/${type})`);
+  return { file: `${phase}/${resolved.fileName}`, phase, domain, type, severity };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {