@xulthekl/team-flow 0.56.1 → 0.58.0

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:**
@@ -63,6 +69,43 @@ Subagent (general-purpose):
     - DRY without premature abstraction?
     - Edge cases handled?
 
+    **Structural criteria (clean-code) — mechanical thresholds:**
+    - **Magic values** (unnamed numeric/string literals) → **Critical**. 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.
+      These thresholds are **readability advisories**. The "Do not use line count as
+      evidence" rule under Minimality And Scope concerns *removing* required code; this
+      one NEVER justifies deleting validation, security, or error handling.
+
+    **Incremental boundary — applies to ALL criteria above and below**: judge only the code
+    units this diff adds or modifies. When a hit sits inside a function that already existed
+    before this change, downgrade it to **Minor** and register it as `存量待整改` in your
+    report — never ask for a rewrite outside the task scope.
+
+    **Structural criteria — mandatory answers** (no threshold: answer AND justify):
+    - **Single responsibility**: can the function name cover ALL steps in the body?
+    - **DRY**: is there a structurally equivalent logic block within this diff OR this
+      repository (ignore comments, whitespace, identifier names)? Answer "yes" only when
+      you cite BOTH `file:line` sides.
+      - Disposition: same shared publish unit (same package / module / directory) →
+        **Critical**, extract a shared layer. Cross-repo duplication is NOT judgeable
+        here (your worktree is single-repo).
+
+    **Judgement cases** — when a structural hit is genuinely not blocking, cite it as
+    `judgement-exception: <id>` **plus the structural similarity** (e.g. "all guard clauses,
+    no nesting"). Match by **structural features, not line count** — the numbers below
+    illustrate the case, they are not thresholds. Available ids:
+    - `P1` — long function (≈37 lines) whose body is all guard clauses, one abstraction level → not blocking
+    - `P2` — cross-repo isomorphic fix, no shared publish unit → not blocking
+    - `N1` — long function (≈54 lines) that is guard clauses + one switch, no nesting → not blocking
+    - `N2` — deep nesting arising from try/catch + guard-clause `continue` → already covered
+      by the nesting rule (cite only if that rule's intent is disputed)
+    - `N4` — ≈35 lines, single abstraction level (error mapping) → advisory only
+    - Magic-value exemptions beyond the criterion's list: no id needed — apply the criterion's
+      own test ("does changing this value change behavior?") and state your reasoning.
+
     **Architecture:**
     - Sound design decisions?
     - Reasonable scalability and performance?
@@ -118,6 +161,18 @@ Subagent (general-purpose):
     a fresh review and replacement `pass` receipt before any dependent wave or
     closing transition.
 
+    ### Structural Criteria (mandatory answers)
+
+    Answer both; cite `file:line` for each. If you downgrade by citing a judgement
+    case, name it here as `judgement-exception: <id>` plus the structural similarity.
+
+    - **Single responsibility**: [Yes | No — if No, list the steps the function name
+      cannot cover, with file:line]
+    - **DRY**: [Yes | No — if Yes, cite BOTH `file:line` sides + shared-layer disposition]
+
+    **存量待整改** (pre-existing hits downgraded to Minor — one per line, or "none"):
+    - [e.g. `src/foo/Bar.java:120` — function length >20 lines, pre-existing]
+
     ### Strengths
     [What's well done? Be specific.]
 
@@ -182,8 +237,23 @@ Subagent (general-purpose):
 - Comprehensive test coverage (18 tests, all edge cases)
 - Good error handling with fallbacks (summarizer.ts:85-92)
 
+### Structural Criteria
+
+- Single responsibility: Yes — each handler covers one step
+- DRY: No — `search.ts:25-27` duplicates the date-validation block in `parse.ts:88-90`
+  (structurally equivalent, comments/identifiers ignored). Same package → shared layer
+  recommended (Critical)
+
 ### Issues
 
+#### Critical (Must Fix)
+1. **Structurally duplicated date-validation block**
+   - File: `search.ts:25-27` (duplicates `parse.ts:88-90`)
+   - Issue: Same package, structurally equivalent — the two copies will drift
+   - Fix: Extract to a shared helper in the package's utils
+   - Note: A Critical finding forces `--verdict fail`; a repair requires a fresh
+     review and a replacement `pass` receipt before any dependent wave
+
 #### Important
 1. **Missing help text in CLI wrapper**
    - File: index-conversations:1-31
@@ -207,7 +277,9 @@ Subagent (general-purpose):
 
 ### Assessment
 
-**Ready to merge: With fixes**
+**Ready to merge: No** — a Critical finding is open
 
-**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+**Reasoning:** Core implementation is solid with good architecture and tests, but the
+structurally duplicated validation block (Critical) must be extracted into a shared layer
+before merge. The Important issues (help text, date validation) are easily fixed.
 ```

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/skills/workflow-orchestrator/references/s5-monitoring.md

@@ -24,10 +24,14 @@
 
 ### 2. 跨 change 一致性检测
 
-调用 `cross-change-consistency-checker` agent（插件 agent，跨 skill 复用价值）检测：
-- 共享聚合/实体的变更是否冲突
-- API 变更是否影响其他 change
-- 原型漂移（change 实现与全局 prototype/ 是否一致）
+调用 `cross-change-consistency-checker` agent（插件 agent，跨 skill 复用价值）检测 5 个维度：
+- 共享聚合/实体的变更是否冲突（Dim 1）
+- API 变更是否影响其他 change（Dim 2）
+- 架构锚点漂移（Dim 3）
+- 原型漂移（change 实现与全局 prototype/ 是否一致）（Dim 4）
+- **同构横展完整性（Dim 5，v0.58.0）**：本 change 处置的代码模式，是否在其**全部**出现位置都已处置
+
+**Dim 5 传参**：须向 agent 传 `repo_layout`（读 `<项目根>/.team-flow/team-flow.config.json` 的 `repo_layout.repos`）；缺失时 agent 跳过 Dim 5 并注明。**触发条件**：change 性质为缺陷修复 / 规则对齐 / 同构同步时启用；纯新功能开发跳过（无既有模式可横展）。**真空对照**：agent 对零命中的模式须显式报告「模式未命中，需人工确认」，不得记为 CLEAN。
 
 ### 3. 复利晋升
 

package/skills/workflow-start/SKILL.md

@@ -141,6 +141,10 @@ The current planned wave is implemented and ready for spec-compliance + code-qua
 ### Route to release-archivist (dispatch sub-agent)
 Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.
 
+**Dim 5 横展完整性检查（v0.58.0）**：`executing → closing` 前，若本 change 性质为缺陷修复 / 规则对齐 / 同构同步，调度 `cross-change-consistency-checker` agent 执行 **Dim 5**——传 `change_dirs`（本 change）+ `repo_layout`（读 `.team-flow/team-flow.config.json` 的 `repo_layout.repos`）。agent 以**模式驱动**扫描本 change diff 中被处置的具名结构元素在**全部仓**的出现位置，差异集即遗漏候选（可达 → Important，须先修复或登记；零调用方 → Minor）。**纯新功能开发跳过**（无既有模式可横展）。**零命中时 agent 须显式报告「模式未命中」而非 CLEAN**（防真空断言）。
+
+> 为何单 change 也要查：横展缺口发生在**单个 change 内部**（v1 实证：一个 change 修了 2 个同构仓、漏了 2 个），而 `cross-change-consistency-checker` 此前仅在 S5（change ≥ 2）被调度——**该场景下 Dim 5 永不触发**。此处是本检查对单 change 的唯一入口。
+
 ### Route to spec-merger
 Delta specs exist that need merging, change closing with ADDED/MODIFIED/REMOVED/RENAMED specs.
 

package/templates/conventions/glaf4-compliant/java-testing.md

@@ -326,7 +326,7 @@ void testGetUser_InactiveUser() { ... }  // status = INACTIVE
 
 ## 8. 测试质量规则
 
-参见 `references/test-quality-rules.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/test-quality-rules.md`，主要包括：
 
 1. 断言质量规则（missing-meaningful-assertion、weak-assertion-only、verify-only-without-assertion）
 2. 调试代码残留规则（system-out、print-stack-trace）
@@ -339,7 +339,7 @@ void testGetUser_InactiveUser() { ... }  // status = INACTIVE
 
 ## 9. 测试隔离
 
-参见 `references/integration-test-isolation.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/integration-test-isolation.md`，主要包括：
 
 - Repository 层：H2 内存库
 - Service 层（同步）：@Transactional
@@ -350,7 +350,7 @@ void testGetUser_InactiveUser() { ... }  // status = INACTIVE
 
 ## 10. 集成测试契约
 
-参见 `references/integration-test-contracts.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/integration-test-contracts.md`，主要包括：
 
 - 入口契约：API 端点、消息队列、定时任务
 - 协作者契约：真实/mock/stub 分级

package/templates/conventions/js-testing.md

@@ -244,7 +244,7 @@ describe('UserService', () => {
 
 ## 7. 测试质量规则
 
-参见 `references/test-quality-rules.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/test-quality-rules.md`，主要包括：
 
 1. 断言质量规则（missing-meaningful-assertion、weak-assertion-only）
 2. 调试代码残留规则（console.log）

package/templates/conventions/python-testing.md

@@ -316,7 +316,7 @@ def mock_external_api(mocker):
 
 ## 9. 测试质量规则
 
-参见 `references/test-quality-rules.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/test-quality-rules.md`，主要包括：
 
 1. 断言质量规则（missing-meaningful-assertion、weak-assertion-only）
 2. 调试代码残留规则（print）

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 的实证教训）。