@xulthekl/team-flow 0.56.1 → 0.57.0

package/skills/ce-compound/references/three-tier-index.md

@@ -4,7 +4,7 @@
 
 ```
 docs/solutions/
-├── INDEX.md                  # L1：轻量索引（≤150行，每条一行摘要+标签）
+├── INDEX.md                  # L1：轻量索引（≤150 条，每条一行摘要+标签）
 ├── prd/                      # 按阶段分目录（枚举权威：scripts/lib/solutions-phases.mjs）
 ├── plan/
 ├── architecture/
@@ -22,9 +22,9 @@ docs/solutions/
 
 ```markdown
 # Solutions Index
-<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
-| date | phase | domain | type | severity | summary | file |
-|------|-------|--------|------|----------|---------|------|
+<!-- 每条一行，排序 severity 降序 → date 降序 → file 兜底，≤150 条上限 -->
+| date | phase | domain | type | severity | summary | file | source |
+|------|-------|--------|------|----------|---------|------|--------|
 ```
 
 ## 经验文件格式
@@ -35,10 +35,13 @@ docs/solutions/
 ---
 phase: prd          # 阶段标签：prd | plan | architecture | prototype | spec | build | review | cross-phase
 domain: auth        # 领域标签（与 PRD/change 的领域对应）
-type: pitfall       # pitfall | pattern | decision | insight
+type: pitfall       # pitfall | pattern | insight（仅 pitfall/pattern 参与晋升；其余保留在 change 级）
 severity: high      # critical | high | medium | low（序定义于 scripts/lib/severity.mjs）
 date: 2026-07-15
-source: change-id   # 来源 change（晋升时保留）
+source: change-id   # 首次晋升的来源 change
+title: 一句话标题     # 检索字段（learnings-researcher 按 title/tags/module/problem_type grep）
+confirmations: [change-a, change-b]   # 确认过这条经验的**全部**来源 change（晋升时追加）
+                                      # —— 每新增一个来源升一档 severity；同 change 重跑不升
 ---
 
 ## 问题描述
@@ -54,6 +57,6 @@ source: change-id   # 来源 change（晋升时保留）
 ## 按需加载策略
 
 三层索引设计使最坏情况 token 消耗约 ~6.5k：
-1. **L1 INDEX.md**：始终加载（≤150 行，每条约 40 token）
+1. **L1 INDEX.md**：始终加载（**≤150 条**，每条约 40 token）
 2. **L2 阶段目录**：按 phase 过滤后加载匹配文件列表
 3. **L3 经验文件**：仅加载与当前任务相关的具体文件

package/skills/ce-compound/references/write-flow.md

@@ -3,17 +3,29 @@
 ## 记录一条经验的步骤
 
 1. 确定 phase/domain/type/severity 标签
-2. 在对应阶段目录下创建经验文件（如 `docs/solutions/prd/2026-07-15-需求歧义.md`）
-3. 在 INDEX.md 中追加一行摘要
-4. 如果 INDEX.md 超过 150 行，执行淘汰规则
+2. 在对应阶段目录下创建经验文件（如 `docs/solutions/prd/2026-07-15-需求歧义.md`），frontmatter **须含 `title:`** —— 它是 `learnings-researcher` 的检索字段（该 agent 按 `title:`/`tags:`/`module:`/`problem_type:` grep）；存量条目可用 `tf solutions backfill` 补齐
+3. **不要手工编辑 `INDEX.md`** —— 见下节
 
-## 淘汰规则（Eviction）
+## INDEX 的维护（v0.57.0 §4.2 变更）
 
-当 INDEX.md 超过 150 行硬上限时：
-- 按 severity 降序排列（critical > high > medium > low；序定义于 `scripts/lib/severity.mjs`）
-- 保留前 150 条
-- 淘汰 low severity 且 date 最早的条目
-- 被淘汰的经验文件保留在阶段目录中（可从文件系统找回），仅从 INDEX.md 移除
+INDEX 是**投影**，唯一写入者是 `scripts/lib/solutions-index-gen.mjs` 的 `refreshIndex()`：
+
+- `tf solutions capture` / `tf solutions promote` 在写完条目文件后调用它（**入口内建**，不靠调用点枚举——两者各有多个落盘分支，逐处追加必然漏改）
+- `tf solutions index-gen` 是它的 CLI 入口
+- **手工改写 INDEX 会在下一次捕获/晋升时被覆盖**——v0.57.0 之前 capture/promote 会直接 append INDEX 行，
+  与 index-gen 的全量重建互为回滚；收敛为单一 writer 后该风险消除
+
+`severity` 与 `confirmations` 的真相源是**条目文件的 frontmatter**（唯一不被重建抹掉的持久层）；
+INDEX 行中的值是它们的投影。可用 `tf doctor` 的 `Solutions` 维度检查两者是否一致。
+
+## 容量与淘汰（v0.57.0）
+
+上限为 **150 条**（`MAX_INDEX_ENTRIES`；**不是 150 行**——INDEX 文件另含 4 行头部）：
+
+- 按 **severity 降序**（critical > high > medium > low；序定义于 `scripts/lib/severity.mjs`）→ **同级按 date 降序** → **同名同级按 file 兜底**（末键保证去留在跨机器上可复现）
+- 保留前 150 条；**被淘汰的经验文件保留在阶段目录中**（仅从 INDEX 移除）
+- **淘汰会显式 WARN 并逐条列出**被丢弃的文件（v0.57.0 前为静默）
+- 条目数逼近上限时 `tf doctor` 的 `Solutions` 维度会预警
 
 ## CLI 写入命令
 
@@ -32,5 +44,5 @@ tf solutions index-gen    # 重建复利索引
 ## 阶段感知注入
 
 ```bash
-tf solutions inject --phase <p> --domain <d>   # 阶段感知注入（top-5）
+tf solutions inject --phase <p> --domain <d> --limit <n>   # 阶段感知注入（默认 top-5，须显式传 --limit）
 ```

package/skills/ce-ideate/references/agents/learnings-researcher.md

@@ -17,9 +17,16 @@ For ideation invocations, search the full learning corpus described below, then
 
 ## Step 0: Ground in CONCEPTS.md (if present)
 
-Before searching `docs/solutions/`, check whether `CONCEPTS.md` exists at the repo root. If it does, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+Before searching `docs/solutions/`, probe for `CONCEPTS.md` in **either** of two locations and read the first one found:
 
-If `CONCEPTS.md` does not exist, skip this step entirely and proceed to Step 1.
+1. `CONCEPTS.md` at the repo root
+2. `docs/architecture/CONCEPTS.md`
+
+If found, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+
+> 两处探测的原因：`workflow-bootstrap` B3 把词汇表产出在 `docs/architecture/CONCEPTS.md`，而本步骤原只查仓库根 ⇒ grounding 静默落空（实测 emp-auth 的 `CONCEPTS.md` 位于 `docs/architecture/`）。与 Step 2「动态探测目录、不假设固定列表」同一原则。
+
+If neither location has `CONCEPTS.md`, skip this step entirely and proceed to Step 1.
 
 ## Search Strategy (Grep-First Filtering)
 

package/skills/ce-ideate/references/grounding.md

@@ -35,7 +35,7 @@ Run grounding agents in parallel in the **foreground** (do not background — re
 
    > **Grounding scope:** use the supplied project context and go directly to current patterns bearing on the focus, pain points, leverage points, applicable workflow constraints, and in surprise-me mode representative files plus recent activity. If the focus cannot be scoped, use one targeted root or workspace probe.
    >
-   > Start with the files and areas named by the focus or caller context. Read `STRATEGY.md` when product alignment matters, and `CONCEPTS.md` when canonical vocabulary matters.
+   > Start with the files and areas named by the focus or caller context. Read `STRATEGY.md` when product alignment matters, and `CONCEPTS.md` when canonical vocabulary matters — the latter lives at **`docs/architecture/CONCEPTS.md`** (repo-root location retired in v0.23.0).
    >
    > If the focus names a root-level `*.md` file, read it and include under `User-named references`. When listed on the research-artifacts line, include only a one-line gist here.
    >

package/skills/ce-plan/references/agents/learnings-researcher.md

@@ -17,9 +17,16 @@ For planning invocations, search the full learning corpus described below, then
 
 ## Step 0: Ground in CONCEPTS.md (if present)
 
-Before searching `docs/solutions/`, check whether `CONCEPTS.md` exists at the repo root. If it does, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+Before searching `docs/solutions/`, probe for `CONCEPTS.md` in **either** of two locations and read the first one found:
 
-If `CONCEPTS.md` does not exist, skip this step entirely and proceed to Step 1.
+1. `CONCEPTS.md` at the repo root
+2. `docs/architecture/CONCEPTS.md`
+
+If found, read it as grounding — it defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+
+> 两处探测的原因：`workflow-bootstrap` B3 把词汇表产出在 `docs/architecture/CONCEPTS.md`，而本步骤原只查仓库根 ⇒ grounding 静默落空（实测 emp-auth 的 `CONCEPTS.md` 位于 `docs/architecture/`）。与 Step 2「动态探测目录、不假设固定列表」同一原则。
+
+If neither location has `CONCEPTS.md`, skip this step entirely and proceed to Step 1.
 
 ## Search Strategy (Grep-First Filtering)
 

package/skills/ce-plan/references/research-workflow.md

@@ -12,7 +12,7 @@ Prepare a concise planning context summary (a paragraph or two) to pass as input
 - If an origin document exists, summarize the problem frame, requirements, and key decisions from that document
 - Otherwise use the feature description directly
 - If `STRATEGY.md` exists, read it and include the relevant pieces (target problem, approach, active tracks) in the summary so downstream research and planning decisions are anchored to product strategy
-- If `CONCEPTS.md` exists at repo root, read it — its definitions are the canonical names for domain entities, named processes, and status concepts. Plan with those terms rather than synonyms.
+- If `CONCEPTS.md` exists — check **repo root first, then `docs/architecture/CONCEPTS.md`** (`workflow-bootstrap` B3 writes it to the latter, so a root-only probe misses bootstrapped projects) — read it: its definitions are the canonical names for domain entities, named processes, and status concepts. Plan with those terms rather than synonyms.
 - Include session-settled decisions with their rejected alternatives, plus the standing line "If you find evidence a settled decision cannot work, report it — do not suppress it." Do not pass the decision's advocacy or rationale, and keep any adversarial or validation lens blind to settlement markers.
 
 Pass the project's active instructions and the planning context summary to `repo-research-analyst`, and send it directly to the requested current scopes. If the feature cannot be scoped from that context, allow one targeted root or workspace probe. Read an exact dependency or runtime version when the plan or an external-doc query materially depends on it.
@@ -45,7 +45,7 @@ Collect:
 - **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
 - **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
 
-**Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = plan OR phase = cross-phase` and `domain` matches the current topic. Inject top-5 summaries as planning constraints. If INDEX.md does not exist or is empty, skip silently.
+**Solutions index (v0.5)**: Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = plan OR phase = cross-phase` and `domain` matches the current topic. Inject the **top 5** summaries as planning constraints, ordered **severity → phase-match → date** (the CLI's ordering); widen with `tf solutions inject --phase plan --limit <n>` when cross-phase entries saturate the window. If INDEX.md does not exist or is empty, skip silently — a missing index makes the CLI print one WARN, which is not an error.
 
 ## 1.1b Detect Execution Direction Signals
 

package/skills/code-reviewer/SKILL.md

@@ -93,6 +93,13 @@ Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI
 
 The code-reviewer agent follows this 6-step process:
 
+### Step 0: Solutions Injection (v0.57.0 §4.1)
+
+Run `tf solutions inject --phase review --limit 15` (never blocks on failure) — it surfaces historical learnings from the `review` and `cross-phase` buckets so this review avoids known pitfalls. Treat the output as **advisory hints, not constraints**; report conflicts with the contract/spec rather than following either silently. On a failed/empty read the CLI prints one WARN and returns empty — continue.
+
+> **Keep `--limit`**: the default top-5 saturates once 5 cross-phase entries exist, making this stage's own (lower-severity) entries unreachable. The flag widens the window only — ordering is unchanged (severity → phase-match → date).
+> **Two dispatch paths, both must inject**: this step covers the `team-flow:code-reviewer` agent path (which preloads this file); `code-reviewer-prompt.md` carries its own copy for the `general-purpose` + template path. Removing either drops injection on that path — gated by `tests/lib/doc-consistency.test.mjs`.
+
 ### Step 1: Gather Context
 
 1. Read `change-brief.md` to understand scope and constraints

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -36,6 +36,12 @@ Subagent (general-purpose):
 
     Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
 
+    ## Solutions Injection
+
+    Before reviewing, run `tf solutions inject --phase review --limit 15` (never blocks on failure) — it surfaces historical learnings from the `review` and `cross-phase` buckets so this review avoids known pitfalls. Treat the output as **advisory hints, not constraints**; report conflicts with the contract/spec rather than silently following either. If the read fails or nothing matches, the CLI prints one WARN line and returns empty — continue the review.
+
+    > **Why this is duplicated from the SKILL.md's `Review Process` step 0**: there are two dispatch paths — (a) a `general-purpose` subagent built from *this template*, and (b) the `team-flow:code-reviewer` agent, which preloads the SKILL.md and therefore already carries that step. Path (b) cannot be relied on here because this template is self-contained (it inlines the checks below), so the injection must be stated in the template too. Removing either copy silently drops the learnings on that path — v0.57.0 P4 shipped with only the SKILL.md copy and this path ran with no injection at all.
+
     ## What to Check
 
     **Spec/Contract alignment:**

package/skills/contract-builder/SKILL.md

@@ -74,6 +74,15 @@ When the change involves UI (design.md has a `## UI Contract` section), the exec
 
 ### Structure
 
+> **模块分段契约（v0.57.0 §4.3）**：`## Cases` 与 `## E2E / AC Verification` 之下的 `### {module}`
+> 才是 `test-merge` 认定的测试模块分段边界（`MODULE_SECTIONS`，**精确段名比较**）；其他段下的 `###`
+> 不作为测试模块。E2E case 以 `test_tier=e2e` 的行落在 `## Cases` 内，故默认**不**单独建
+> `## E2E / AC Verification` 段。
+>
+> 注意残留形态：白名单只约束**分段**，不约束**模块名的字符构成** —— 全标点标题会产出
+> `2026-09-12-.md` 这类无信息文件名；且**历史退化 baseline 不会被清理**（既不从索引消失，
+> 也不改名），INDEX 的模块行由文件名反推、与 `MODULE_SECTIONS` 不同源。
+
 ```markdown
 # Test Matrix — {change-name}
 

package/skills/release-archivist/SKILL.md

@@ -77,7 +77,7 @@ Check for files modified outside scope fence, new dependencies not in design. Un
 
 - **Architecture merge**: <merged architecture.md + database.md + api.md + N SQL scripts to docs/architecture/ | architecture/ absent — skipped>
 - **Prototype sync**: <synced N pages / N components / design-system updated | no UX delta | conflicts: N>
-- **Compound promotion**: <promoted N learnings / updated N confirmed patterns | no learnings>
+- **Compound promotion**: <promoted N / confirmed N / unchanged N / skipped N | no learnings>
 
 **Verdict**: PASS (all PASS) / CONDITIONAL (WARN only) / FAIL (any FAIL).
 - FAIL → fix issues or route back to build-executor
@@ -231,7 +231,7 @@ Promote change-level learnings to the global solutions library:
 tf solutions promote <change-dir>
 ```
 
-读取 change 根目录的 `learnings.md`（v0.49.0 §83.3.5 路径统一）——`severity ≥ medium` 且 `type = pitfall|pattern` 者晋升全局 `docs/solutions/`；命中既有条目则标记 confirmed pattern 并升级 severity。severity 序 `critical > high > medium > low` 定义在插件内 `scripts/lib/severity.mjs`（引用，非调用）（v0.23 §91，单一来源）。
+读取 change 根目录的 `learnings.md`（v0.49.0 §83.3.5 路径统一）——`severity ≥ medium` 且 `type = pitfall|pattern` 者晋升全局 `docs/solutions/`；命中既有条目（文件名 + 正文签名**都**相同）则把来源 change 登记进 `confirmations` 并按其升级 severity（新来源才升一档，同 change 重跑不升）；同标题但正文不同者是**独立条目**（文件名加 `-2`/`-3` 后缀），正文一律不合并（v0.57.0 废止 `domain+type` 判重合并正文的旧行为）。severity 序 `critical > high > medium > low` 定义在插件内 `scripts/lib/severity.mjs`（引用，非调用）（v0.23 §91，单一来源）。
 
 **Compound Capture Check（v0.5）**：closing 前自检本 change 是否产生了可沉淀的经验（强制回退 / 复发根因 / 范围外扩 / 契约漂移）；有则写入 change 根的 `learnings.md`，每条 `## <title>` 带 frontmatter（`phase`/`domain`/`type`/`severity`/`date`）。该文件正是 `compound-captured` guard 检查、`tf solutions promote` 读取的对象。
 

package/skills/release-archivist/references/closing-procedures.md

@@ -33,7 +33,9 @@ tf solutions promote <change-dir>
 
 Promotion criteria:
 - severity ≥ medium AND type = pitfall/pattern → promote to global `docs/solutions/`
-- domain+type matches existing global entry → mark as "confirmed pattern", upgrade severity (low → medium → high → critical)
+- file name AND body signature both match an existing global entry → register the source change in `confirmations` and upgrade severity (low → medium → high → critical); same title but different body is a SEPARATE entry (file suffixed `-2`/`-3`) — bodies are never merged
+- **severity steps up once per NEW source change** — re-running promote for a change already listed in `confirmations` reports `unchanged` and does NOT upgrade (a re-run is not new evidence). Both `severity` and `confirmations` are written to the **entry file's frontmatter**, never to INDEX (INDEX is derived by `refreshIndex`)
+- `tf solutions promote` prints four counts (`promoted` / `confirmed` / `unchanged` / `skipped`) — record them verbatim in the closing summary; `skipped` entries are listed with reasons and are NOT errors (most commonly: `severity` below medium, or a `phase` outside the enum)
 
 Report promotion results in the closing summary. Promotion is advisory — failures do not block closing.
 

package/skills/spec-writer/SKILL.md

@@ -27,7 +27,7 @@ If no prototype exists or it is empty, skip silently — not all projects have p
 
 ### Solutions Index (v0.5)
 
-Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = spec OR phase = cross-phase` and `domain` matches the current change's domain. Inject top-5 summaries as context constraints for artifact generation. If INDEX.md does not exist or is empty, skip silently.
+Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = spec OR phase = cross-phase` and `domain` matches the current change's domain. Inject the **top 5** summaries as context constraints for artifact generation, ordered **severity → phase-match → date** (the CLI's ordering); widen with `tf solutions inject --phase spec --limit <n>` when cross-phase entries saturate the window. If INDEX.md does not exist or is empty, skip silently — a missing index makes the CLI print one WARN, which is not an error.
 
 ### Change Brief (v0.9)
 

package/skills/workflow-orchestrator/SKILL.md

@@ -37,7 +37,7 @@ Do NOT invoke for:
 ## Execution Flow（S1-S5 + ARCH 产品级架构设计）
 
 ### S1: 路径路由器
-**先做需求选择**（v0.15.0 多需求）：读 `.team-flow/registry.yaml`，确定 `active_requirement`（多需求则询问操作哪个/新建）。再判断 7 种入口路径之一；检查 baseline.md / CONCEPTS.md 并注入；复利注入（INDEX.md top-5）。**路由结果必须向用户显式确认**（路由是建议非决定）。详见 `references/s1-path-router.md`。
+**先做需求选择**（v0.15.0 多需求）：读 `.team-flow/registry.yaml`，确定 `active_requirement`（多需求则询问操作哪个/新建）。再判断 7 种入口路径之一；检查 baseline.md / CONCEPTS.md（后者在 `docs/architecture/CONCEPTS.md`，根目录为旧位置）并注入；复利注入（INDEX.md 默认 top-5，见 `references/s1-path-router.md` 的窗口与排序口径）。**路由结果必须向用户显式确认**（路由是建议非决定）。详见 `references/s1-path-router.md`。
 
 **conventions 注入（v0.11 §33）**：
 - 读取 conventions 配置，注入为需求分析上下文
@@ -205,7 +205,7 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 - **架构门禁（v0.36.0）**：ARCH 阶段 skip 必须物化（`iterations/vN/SKIPPED` + 理由）；arch-readiness（S4 拆分：快照覆盖 change 触及 BC）与 arch-snapshot（change closing）为 guard 门禁，`arch_baseline` 缺失 → WARN 不 FAIL（存量豁免）
 - **路由是建议非决定**：S1 路由判断必须用户确认；重规划必须 DP-R 阻塞确认
 - **回退必写 replan_log**：active → pending 回退必须记录；受影响制品归档为 .revN，重入不读旧制品
-- **不阻断流程**：所有复利操作为 advisory 级，INDEX.md 读取失败时静默跳过
+- **不阻断流程**：所有复利操作为 advisory 级——INDEX 缺失/读取失败时 CLI 输出一行 WARN 并返回空结果，**不阻断流程**（v0.57.0 前为完全静默）
 - **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37)：子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`，prototype-builder → `prototype/` 目录）。主代理（workflow-orchestrator）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证。编排层自己负责的产物（change-brief.md、orchestrator.yaml、审计报告落盘）不受此限制
 
 ## Output Standard

package/skills/workflow-orchestrator/references/s1-path-router.md

@@ -40,11 +40,13 @@ S1 只做编排动作（需求选择、存在性检查、路径判断、阻塞
 - 检查 `docs/architecture/baseline.md`：
   - 存在 → 注入为架构上下文（技术栈/模块/数据模型），替代「从零侦察」
   - 不存在 → advisory 提示「建议先运行 `/workflow-bootstrap` 建立项目基线」（**不阻断**）
-- 检查 `CONCEPTS.md`：存在 → 注入领域词汇表
+- 检查 `CONCEPTS.md`（**位于 `docs/architecture/CONCEPTS.md`**，根目录为 v0.23.0 前的旧位置）：存在 → 注入领域词汇表
 
 ## 复利注入（advisory 级）
 
-读取 `docs/solutions/INDEX.md`（如存在），过滤 `phase = prd OR cross-phase` 且 domain 匹配的经验，取 top-5（按 severity 降序）摘要注入为上下文约束。读取失败时静默跳过，不阻断。
+读取 `docs/solutions/INDEX.md`（如存在），过滤 `phase = prd OR cross-phase` 且 domain 匹配的经验，取 **默认 top-5** 摘要注入为上下文约束。读取失败时跳过、不阻断（**无索引时 CLI 会输出一行 WARN 并返回空结果，那不是错误**）。
+
+> **窗口与排序须与 CLI 同口径（v0.57.0）**：排序为 **severity 降序 → 阶段匹配度（本阶段优先于通配的 cross-phase）→ date 降序**（三级键；旧的"仅 severity 降序"已被取代）。窗口默认 5，用 `tf solutions inject --phase <p> --limit <n>` 放宽——cross-phase 条目满载 5 条时，本阶段新增条目**永不可达**，故凡有 CLI 可用的场合优先用 CLI（`--all` 输出全部，但无上界，慎用）。同 `source` 的条目折叠为 1 条并标注条数。
 
 工作流模式复利（L2）：S1 路由时额外注入历史 `workflow_pattern` top-3（confidence ≥ 0.5）。详见 state-model.md「工作流模式复利 L2」。
 

package/skills/workflow-orchestrator/references/s3-plan-pipeline.md

@@ -35,7 +35,7 @@ ce-plan 在 orchestrator pipeline 上下文中减少仪式开销，但**保留
 
 ## 复利
 
-- **注入**：读取 `docs/solutions/INDEX.md`，过滤 `phase = plan OR cross-phase`，取 top-5 摘要
+- **注入**：读取 `docs/solutions/INDEX.md`，过滤 `phase = plan OR cross-phase`，取默认 top-5 摘要（窗口与排序口径见 `s1-path-router.md`；有 CLI 时优先 `tf solutions inject --phase plan --limit <n>`）
 - **捕获**：检测可复利时刻（技术方向决策、拆分权衡等）
 
 ## 反馈环路检查点

package/templates/learnings.md

@@ -4,7 +4,7 @@
 >
 > **位置权威（v0.49.0 §83.3.5）**：`changes/<name>/learnings.md`。代码（`solutions-promote.mjs`）与 `compound-captured` guard 均只认此路径；文档曾宣称的 `specs/<cap>/learnings.md` 从未落地。
 >
-> **消费链路**：本文件 → `tf solutions promote`（release-archivist closing 调用）→ 全局 `docs/solutions/` → `tf solutions inject`（各阶段入口注入）。
+> **消费链路**：本文件 → `tf solutions promote`（release-archivist closing 调用）→ 全局 `docs/solutions/` → `tf solutions inject --phase <p> --limit <n>`（各阶段入口注入；**须显式传 `--limit`**，默认 top-5）。
 >
 > **晋升前提**：只有带完整 frontmatter 的条目才会被晋升。缺字段时按默认 `severity=low` / `type=insight` 处理，不满足晋升条件即跳过——promote 会在输出中列出跳过原因，不再静默。
 >
@@ -12,8 +12,12 @@
 
 ## 1. <条目标题：一句话说清问题或模式>
 
+> **条目结构**：一个 H2 标题 = 一条经验。正文用下面的 `- **要点**：` 列表写，
+> **不要**在条目内再用 `## 子标题`——H2 是条目分隔符，子标题会被解析成"缺 frontmatter 的条目"
+> 而在 promote 输出中刷出一串 skipped 噪音。
+
 ---
-phase: cross-phase        # 阶段名（prd/plan/architecture/prototype/spec/build/review/cross-phase）或具体领域阶段
+phase: cross-phase        # 阶段名（prd/plan/architecture/prototype/spec/build/review/cross-phase）（不在枚举内会被 promote 跳过并给出理由）
 domain: <领域>            # 如 jest / sdd / spring-boot；注入时按领域过滤
 type: pitfall             # pitfall | pattern | insight
 severity: medium          # critical | high | medium | low（小写；critical = 安全/数据/合规级高危经验）
@@ -44,8 +48,16 @@ date: YYYY-MM-DD
 
 | 条件 | 行为 |
 |---|---|
-| `severity` ≥ medium 且 `type` = pitfall / pattern | 晋升到全局 `docs/solutions/<phase>/`，并追加 INDEX 行 |
-| 与全局 INDEX 已有条目 domain + type 匹配 | 不新建文件：升级已有条目 severity（low → medium → high → critical）+ 条目 frontmatter `confirmed` 计数 +1 + 更新 INDEX 行 |
-| 其他 | 保留在本文件；promote 输出中列为 skipped 并附原因 |
+| `severity` ≥ medium 且 `type` = pitfall / pattern | 晋升到全局 `docs/solutions/<phase>/`（INDEX 由脚本内部重建，**勿手工编辑 INDEX**） |
+| 文件名（`<date>-<slug>.md`）与正文**都**与既有条目相同 | 不新建文件：在条目 frontmatter 的 `confirmations` 追加来源 change + 按其升级 severity（同 change 重跑记为 unchanged，**不**升档） |
+| 与既有条目**同标题但正文不同** | 是**另一条**经验：新建条目（文件名加 `-2`/`-3` 后缀）——**不要**为了去重而合并正文 |
+| `phase` 不在枚举内 / `severity` < medium / `type` 非 pitfall·pattern | 保留在本文件；promote 输出中列为 skipped 并附原因 |
+
+**每条经验独立成条**：不同经验即使标题相同也各自落盘，正文一律不合并（v0.57.0 起；
+旧实现按 `domain+type` 合并正文，实测丢失 13 条内容）。
+
+**幂等的前提是 `date`**：条目文件名是 `<date>-<slug>.md`，故幂等只在**同一 `date` 内**成立。
+条目缺 `date:` 时 promote 按**运行日**计算 —— 跨天重跑会新建条目（而非记 `unchanged`）。
+需要幂等的场景请显式写 `date:`。
 
 **条目质量要求**：写「正确做法」前先验证它在系统层面成立——局部观察得出的 workaround 若被沉淀为通则，会被后续 change 当经验复用，反而固化缺陷（v0.49.0 §83.2.2 的实证教训）。