@xulthekl/team-flow 0.56.1 → 0.57.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.56.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.57.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback + independent business analysis. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.56.1",
+      "version": "0.57.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.56.1",
+  "version": "0.57.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). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.56.1",
+  "version": "0.57.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.56.1"
+    "version": "0.57.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "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). 26 skills + 17 agents, one install.",
-  "version": "0.56.1",
+  "version": "0.57.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.56.1"
+    "version": "0.57.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.56.1",
+      "version": "0.57.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -109,9 +109,9 @@ prototype/             全局原型系统（UI 契约真相源）：index.html /
 docs/
   ├── architecture/    全局架构三层（v0.36.0）：L1 当前态（ARCHITECTURE.md marker 区 / PHYSICAL-MODEL.md / DATABASE.md / API-INDEX.md / INDEX.md / domains/<bc>.md / diagrams/ / schema-baseline.sql / baseline.md）+ L2 changelog/ + L3 iterations/vN/architecture.md（产品级快照，archived 退役）
   └── solutions/       复利经验库（v0.5 新增，三层索引）
-      ├── INDEX.md     # L1 轻量索引（≤150行，每条一行摘要+标签）
+      ├── INDEX.md     # L1 轻量索引（≤150 条，每条一行摘要+标签）
       ├── prd/ plan/ architecture/ prototype/ spec/ build/ review/ cross-phase/  # L2 分阶段目录（枚举权威：scripts/lib/solutions-phases.mjs）
-      └── <file>.md    # L3 经验文件（YAML frontmatter: phase/domain/type/severity）
+      └── <file>.md    # L3 经验文件（YAML frontmatter: phase/domain/type/severity/date/source/title/confirmations）
 changes/<name>/        变更脚手架（S4 创建）：.team-flow.yaml（变更级状态文件）/ change-brief.md（产品级交接物，含 upstream_arch_ref）/ proposal.md / design.md / tasks.md / execution-contract.md / learnings.md（变更级经验台账）/ architecture/（变更级三件套 + sql/）
 specs/<cap>/            每变更规格：spec.md（v0.49.0 §83.3.5：learnings.md 归 change 根，不在此目录）
 STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
@@ -134,7 +134,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
   产品级编排层（workflow-orchestrator，v0.7 重设计 + v0.15.0 多需求）
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   S1 路径路由器 → 需求选择（.team-flow/registry.yaml）+ 判断入口路径
-     检查 baseline.md / CONCEPTS.md → 注入上下文 + 复利注入（top-5）
+     检查 baseline.md / CONCEPTS.md → 注入上下文 + 复利注入（默认 top-5，调用点显式 `--limit`）
   S2 PRD + 原型阶段 → ce-brainstorm 产出 PRD
      冻结前 PRD 完整性评审（prd-completeness-reviewer，v0.15.0）
      原型循环由 orchestrator 直接编排（prototype skill 内部编排器，主代理只编排）：
@@ -252,26 +252,32 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 
 ```
 docs/solutions/
-├── INDEX.md                  # L1：轻量索引（≤150行，每条一行摘要+标签，按 severity 降序）
+├── INDEX.md                  # L1：轻量索引（≤150 条，每条一行摘要+标签；排序 severity → date → file）
 ├── prd/ plan/ architecture/ prototype/ spec/ build/ review/ cross-phase/  # L2：分阶段目录（枚举权威：scripts/lib/solutions-phases.mjs）
-└── <date>-<summary>.md      # L3：经验文件（YAML frontmatter: phase/domain/type/severity/date/source）
+└── <date>-<slug>.md         # L3：经验文件（YAML frontmatter: phase/domain/type/severity/date/source/title/confirmations）
 ```
 
-### 四个核心动作
+### 核心动作（五）
 
 | 动作 | 触发时机 | CLI |
 |------|---------|-----|
-| **注入** | 进入每阶段时，自动加载相关经验（top-5） | `tf solutions inject --phase <p> --domain <d>` |
+| **注入** | 进入每阶段时，自动加载相关经验（默认 top-5，**调用方须显式 `--limit`**） | `tf solutions inject --phase <p> --domain <d> --limit <n>` |
 | **捕获** | 阶段转换点检测到可复利时刻 | `tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>"` |
 | **索引重建** | INDEX.md 损坏或手动触发 | `tf solutions index-gen` |
 | **晋升** | change closing 时，经验验证后晋升为产品级 | `tf solutions promote <change-dir>` |
+| **补字段** | 存量条目缺 `title:` 时（learnings-researcher 按它检索） | `tf solutions backfill [--dry-run]` |
+
+> **注入语义（v0.57.0）**：`--phase` 的 `cross-phase` 是**通配符**——任何 phase 查询都会一并返回它，
+> 故 `--phase prd` 在无 prd 条目的项目上注入的就是 cross-phase 那批。默认 top-5 在 cross-phase
+> 条目已达 5 条时**满载**，本阶段新增条目（低 severity）永不可达，故存在调用点时必须显式传 `--limit`。
 
 ### 关键约束
 
-- 所有复利操作为 **advisory 级**，INDEX.md 读取失败时静默跳过，不阻断流程
-- INDEX.md 硬上限 150 行，超限时按 severity 降序保留，淘汰 low + 最早条目
-- 晋升条件：severity ≥ medium 且 type = pitfall/pattern；与全局已有条目 domain+type 匹配则标记"已确认模式"并升级 severity
-- 上下文占用控制：最坏 ~6.5k token（L1 索引全量加载）
+- 所有复利操作为 **advisory 级**：INDEX 缺失/读取失败时 CLI 输出一行 WARN 并返回空结果，**不阻断流程**（v0.57.0 前为完全静默，无人可见"注入其实没发生"）
+- INDEX.md 硬上限 **150 条**（`MAX_INDEX_ENTRIES`，非行数），超限时按 **severity → date → file** 三级序保留（末键保证同日同 severity 的去留在跨机器上可复现）；被淘汰的文件保留在阶段目录中且**逐条 WARN 列出**（v0.57.0 前为静默）
+- 晋升条件：severity ≥ medium 且 type = pitfall/pattern。**命中既有条目（文件名 + 正文签名都相同）**则登记来源 change 到 `confirmations` 并按其升级 severity（`low → medium → high → critical`，新来源才升一档、重跑不升）——**不合并正文**（v0.57.0 废止 `domain+type` 合并：旧实现只把计数 +1 而丢弃正文，实测丢 13 条）。同名但正文不同的经验是**两条独立条目**，碰撞时文件名加 `-2`/`-3` 后缀
+- INDEX.md 是**派生物**，唯一写入者是 `refreshIndex()`（capture/promote 内部调用）——**禁止手工编辑 INDEX**
+- 上下文占用控制：最坏 ~6.5k token（L1 索引全量加载）；注入时**同源条目**（同 `source`）折叠为 1 条 + 标注条数，避免一次事故的多个面占满窗口
 
 ## 配置注入（插件层扩展字段）
 

package/CHANGELOG.md

@@ -4,6 +4,91 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.57.0] - 2026-09-12
+
+### Changed（复利机制 P1 重构；**含 4 项行为变更，升级必读**）
+
+设计来源：`docs/plan/compound-lifecycle-governance-design.md` **v2.3**（P1.5 完整档**三轮**对抗验证：37 + 32 + 11 = **80 项问题全部采纳**，三轮 Critical 全闭合；P4 双门禁评审（plugin-validator + skill-reviewer）**均判 FAIL**，据此另修 **12 项**（5 Critical），见该文档附录 C.4）。
+
+**① 判重语义：废止 `domain+type` 合并（D1-B，最高影响）**
+
+旧实现命中同 `domain+type` 即"合并"，只把 `confirmed` 计数 +1 而**正文丢弃**——emp-auth 实测 **13 条内容丢失**（仅存于 change 的 `learnings.md`，其中含 2 条 critical 因旧 bug 从未晋升）。
+
+- **改为**：每条经验**独立成条**，内容零丢失；跨 change 的"复发"信号改由 `confirmations: [change-id…]` 来源集合承载
+- **幂等由「文件名 + 正文签名」保证**：同 change 重复 promote 记为 `unchanged`（旧实现每次重跑都 +1 confirmed 并升一档 severity，实测连跑 3 次即把 `medium` 推到 `critical`）
+  - ⚠️ **P4 修正**：初版仅用文件名作身份键，`cleanTitle` 剥离序号后 `## 3. 契约漂移` 与 `## 7. 契约漂移` 产出同一 slug ⇒ 第二条被判"已登记"直接跳过 ⇒ **正文与 severity 整条消失**（隔离复现证实，本版新引入的回归）。现身份 = 标题分量（**清洗后**，因序号是 change 局部编号）+ 内容分量（**不清洗**，区分同标题经验），碰撞时探测 `-2`/`-3` 后缀
+- **行为变更**：**同标题但正文不同**的经验现在各自成条（旧版会静默丢弃后一条）；同 change 重跑仍为 `unchanged`，但跨 change 的确认需"标题与正文都相同"——触发窗口比初版更窄（零丢失优先于复发信号）
+
+**② INDEX 写入权收归单一入口**
+
+旧实现有 **3 个 writer** 互相回滚：`promote` 只升 INDEX 行的 severity、`capture` 自建表头 + append、`index-gen` 从零重建（且**无任何流程调用者**）。实测：先 promote 再 index-gen 会把 `critical` **打回 `high`**（3/20 条）、`summary` 被改写（14/20 条）。
+
+- **改为**：`refreshIndex()` 为唯一写入者；`capture`/`promote` 写完条目文件后调用它（**入口内建**，不靠调用点枚举——两者各有多个落盘分支，逐处追加必然漏改）
+- `severity` 与 `confirmations` 的**真相源落条目文件 frontmatter**（唯一不被重建抹掉的持久层）
+- **否决**"重建时取 `max(旧 INDEX, 文件)`"——那会让 INDEX 成为并列真值源，把漂移固化为**不可降档**的不变量
+- 目录缺失时 `refreshIndex` **创建**而非 `exit 1`（旧 `index-gen` 会直接失败，中断首次晋升链）
+- **行为变更**：手工编辑 `INDEX.md` 会在下次捕获/晋升时被覆盖（`skills/ce-compound/references/write-flow.md` 已同步）
+
+**③ `tf test-merge` 的模块边界改为多段白名单**
+
+`extractModuleSections` 的 docstring 写「`## Cases` 下的 `###` 子段」，**实现却是全文扫描所有 `### `**。emp-auth 实测 v1-C1 的 21 个 `###` 中 **12 个是附录/台账段**（`### 执行结果（三仓实测…）`、`### Task 5.x`、`### W6-1 / W6-2 收口`），生成 440–520B 的无复用价值 baseline。
+
+- **改为**：白名单 = `## Cases` + **`## E2E / AC Verification`**（后者是 v0.38.0 引入 E2E 层级时的遗漏——只列 `## Cases` 会让 `vrm4teamflow` 的 `### AC1..AC8`（**32 个 AC/E2E 用例**）**静默冻结**：落选文件不会从 INDEX 消失，因 `rewriteIndex` 扫目录 ⇒ 既无报错也无计数变化）
+- 精确段名比较（`## Adversarial Cases` 含子串 `Cases`，用 `includes` 会误判）
+- 无白名单段时**回退全文扫描 + WARN**（旧实现静默打印 `0 modules processed`）
+- 导出 `extractModuleSections` / `MODULE_SECTIONS` 并补**真实 test-matrix 形态**测试（原 fixture 全是内联 `### Foo` 块，无法捕获本类缺陷）
+- **行为变更**：升级后新 `###` 若位于白名单段之外，**不再生成 baseline**；既有文件不受影响（不删除）
+
+**④ `tf solutions inject` 的排序与容量**
+
+- 排序补两级次级键：**阶段匹配度**（本阶段优先于通配的 `cross-phase`）→ **date 降序**（新条目优先）。旧实现仅 `severityRank` 单键，同级顺序取决于 INDEX 行序 ⇒ 旧条目永久压制新条目
+- 新增 `--limit <n>`（默认仍 5）与 `--all`；`--phase build` 与 `--phase cross-phase` 在旧实现下输出**只差表头**（cross-phase 是通配符），故 `build-executor` 改传 `--phase build` 并**删除**重复的 cross-phase 调用；`code-reviewer` 新增 `--phase review`（审查阶段此前无任何消费方）
+- **同源聚类**（P4 补实现）：同 `source` 的条目（同一次事故的多个面）折叠为 1 条 + 标注条数，把 top-N 槽位还给其他经验。仅作用于**展示**，不合并内容（与 ① 的 D1-B 一致）。INDEX 加 `source` 列（7→8，消费方对 7/8 列都容错）
+- ⚠️ **P4 修正**：初版只加了参数**没改任何调用点**（4 处全未传 `--limit`）——正是设计 §4.1 预警的"可配但没人配"。现 4 处全补 `--limit 15`，并加机械门禁断言"每个 inject 调用点必带 `--limit`/`--all`"
+- **行为变更**：同一批条目的 top-5 **内容与顺序可能变化**
+
+### Added
+
+- `tf solutions backfill [--dry-run]`：为存量条目补写 `title:` 字段（`learnings-researcher` 按 `title:`/`tags:`/`module:`/`problem_type:` grep，而 CLI 条目此前只有 `phase/domain/type/...` ⇒ 实测四模式在 emp-auth 21 条中**各只命中 1 条**）
+- `tf doctor` 新增 `Solutions` 维度（四类检查）：INDEX↔文件漂移、条目数/截断、非白名单目录与平铺文件、未 promote 的 change
+- 共享层新增 `md-normalize.parseTableRow`（**保留空列**的表格行解析）与 `solutions-index-gen.refreshIndex` / `parseFrontmatter` / `MAX_INDEX_ENTRIES`
+- `tests/lib/doc-consistency.test.mjs`（**机械门禁**）：把"同口径副本"清单固化为断言——**10 个**已废止口径短语零命中（含历史溯源行豁免）+ "每个 inject 调用点必带 `--limit`/`--all`"+ **正例/负例对照组**（防止断言退化为真空）。动因：本仓"修复未传播"已复发 4 次（v0.38.0 / v0.53.0 / v0.55.0 / v0.57.0 单次改动发现 8 处残留）
+- `scripts/lib/solutions-entry.mjs`（**共享层**）：条目身份（正文签名 + 碰撞定位）与 **frontmatter 读取**（含行尾注释剥离）的共享实现，capture / index-gen / cmd-doctor 及 promote 的 `parseLearnings` 共用；`promote.confirmByFile`（需整块替换）与 `backfill`（仅键存在性检测）为**已知例外**，理由见各自注释
+- `solutions-backfill.mjs` 与 3 个测试文件（`solutions-backfill` / `cmd-doctor-solutions` + inject/index-gen/promote/test-merge 的扩充用例）
+
+### Fixed
+
+- **列解析空列错位**：`filter(Boolean)` 丢空列且守卫只有下界 ⇒ 单元格含 `|` 时列数错位不被拦截。`inject`、`test-merge` 的 `extractCandidateLedger`/`extractDeferredItems` 改用 `parseTableRow` + 上下界校验；`promote` 的那处随判重通道整体删除（它已不再解析 INDEX）。另横展 `test-merge` 内 **4 处**仍在用的 inline 表格切分（`test-merge` 在 v0.38.0 修过同型缺陷，当时未横展到其余各处）
+- **INDEX 单元格转义**（P4）：内容含 `|` 会让该行列数膨胀 ⇒ 消费方列数校验丢弃整行 ⇒ 条目**永久隐身**，且 doctor 的修复建议（重跑 index-gen）产出同一坏行 ⇒ **死循环**。生成侧转义 `\|`、解析侧还原，并加 `file` 列语义校验兜住"列数在界内但已错位"
+- **`promote` 幂等判据塌缩**（P4，本版 ① 引入的回归）：见 ① 的 P4 修正条
+- **`refreshIndex` 排序不确定**（P4）：同日同 severity 条目在 `maxEntries` 边界的去留取决于 `readdirSync` 顺序 ⇒ 补文件名作决定性末键
+- **条目 frontmatter 值不剥行尾注释**（P4）：`severity: high # 说明` 会被当作未知值原样返回 ⇒ 该条**永不升级且无提示**
+- **`parseTableRow` 同名冲突**（P4）：本仓有 3 份同名不同语义实现（`md-normalize` 永不返回 null / `arch-parse` 与 `ds-parse` 返回 null 且做清洗）⇒ 补差异矩阵注释防止按名误挑
+- **`promote` 缺 phase 白名单校验**（`capture` 一直有）：实测接受 `phase: tools` 会建出 `docs/solutions/tools/` 并追加 INDEX 行，随后重建时该目录不被扫描 ⇒ 条目**静默消失且不计入 dropped**
+- **截断由静默改为可见**：`refreshIndex` 超 150 条时 WARN 并逐条列出被丢弃的文件（旧实现只打印一行计数）
+- **索引缺失由静默改为 WARN**：`solutions-inject` 原输出一行 HTML 注释并以 0 退出，无人可见
+- **`CONCEPTS.md` 路径**：`learnings-researcher` 只查仓库根，而 `workflow-bootstrap` B3 产出在 `docs/architecture/` ⇒ grounding 静默落空；改为两处探测
+- `MAX_INDEX_LINES` → `MAX_INDEX_ENTRIES`：该常量约束的是**条目数**（`entries.slice(0, N)`），但全仓 **15 处**文案写作"150 行"（文件另含 4 行头部，封顶时实为 154 行）
+
+### 验证
+
+- 全量测试 **1199/1199 通过**（基线 1112 项 —— 即 v0.56.1 的测试数，故 +87）
+- **变异验证**（本轮 3 项，均确认新增测试具备判别力）：
+  - 排序反向 → 「全部 critical 条目须被保留」等 3 条失败
+  - 白名单退化为「任意 `##` 段」（等价原全文扫描）→ 4 条边界用例失败，报「附录段「执行结果（三仓实测，命令 + 实际输出）」不得被当作测试模块」
+  - 去掉 `resolveBaselinePath` 的 legacy 回退 → v0.56.1 的回归用例失败
+  - **[P4]** `escapeCell` 不转义 `|` → index-gen 的管道符用例失败
+  - **[P4]** 去掉同源聚类 → inject 的聚类用例失败
+  - **[P4]** 身份键退化为单文件名（复现原缺陷）→ 「两条同标题经验都应落盘」报 `1 !== 2`
+  - **[P4]** 往 skill 注入肯定式旧口径 / 无 `--limit` 的 inject 命令 → doc-consistency 门禁精确报出行号与豁免提示
+- **P4 双门禁结论（七轮）**：每轮均由独立 agent 隔离复现；**前三轮均判 FAIL**，第四轮 reviewer PASS + validator 另报阻断，**第五~七轮 validator 均 PASS（0 阻断）**——七轮共处置 **52 项**：
+  - 第一轮（16 项，含 1 Critical）：**promote 身份键塌缩丢条**（本版新引入的回归，已隔离复现）→ 身份改为「标题分量 + 正文签名」；`--limit` 调用点落实数为 0；口径传播未闭合
+  - 第二轮（13 项，含 3 Critical）：`solutions-capture` **无碰撞保护会静默覆盖**（使 ①「内容零丢失」在 capture 通道为假）→ 抽 `solutions-entry.mjs` 共享层；frontmatter 注释剥离只落在 promote 一条读取路径；两处假闭合；门禁真空断言
+  - 第三轮（11 项，含 2 阻断）：`frontmatterBlock` 的 `(?:^|\n)` 误吞正文水平线 ⇒ **INDEX 出现幽灵条目**（本轮新引入的回归，已补反例断言）；`code-reviewer` 的注入只覆盖 agent 路径、`code-reviewer-prompt.md` 路径零处 inject（假闭合）→ 两条路径都注入 + 新增**正向存在性门禁**
+  - 第四/五轮：`frontmatterBlock` 的宽松匹配**三轮修复未触根因**（一轮放宽正则 → 二轮加防线 → 三轮加领域键校验），第四轮**换判据**（严格锚定段首）才闭合——前三轮都在"加防线"，真问题是判据查的是"块内有没有领域键"而非"该块是文件自身的 frontmatter"；第五轮 validator 判 **PASS（0 阻断）**
+  - 第五轮：validator **PASS（0 阻断）**；第六轮另报 1 项本轮引入的新失效面（`tf doctor` 的 Solutions 维度遇非普通文件抛异常 ⇒ **中止整轮巡检**，12 个维度全丢）——已把「条目枚举」抽为共享层 `listSolutionEntries`（判据 + 两层防御），三个消费方（`index-gen` / `cmd-doctor` / `backfill`）共用
+  - 逐轮闭合表见设计文档附录 **C.4 – C.10**；由此新增的机械门禁 `tests/lib/doc-consistency.test.mjs` 已含正例/负例对照组、`INJECT_CONSUMERS` 正向存在性与窗口参数断言
+
 ## [0.56.1] - 2026-09-12
 
 ### Fixed（v0.56.0 自身引入的回归 + P1.5 第一轮暴露的遗漏；**升级优先于 0.56.0**）

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.56.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.57.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.56.1**。
+当前发布版本：**v0.57.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.56.1`
+> 当前版本：`v0.57.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.56.1`
+- Current: `v0.57.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

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

@@ -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",
+  "version": "0.57.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.57.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.57.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.57.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.56.1",
+  "version": "0.57.0",
   "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.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.56.1",
+  "version": "0.57.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). 26 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, '|'));
+}