@xulthekl/team-flow 0.48.0 → 0.50.0

package/skills/contract-builder/references/glaf4-delegation.md

@@ -112,15 +112,15 @@ bridging：contract-builder 产非空骨架矩阵 test-matrix.md（过 test-matr
   → tf state rebuild（过 test-matrix-complete 出口门）
 ```
 
-## 8. closing 时序协议（v2.1 §6.3，I5 固化防 plan 过期卡死）
+## 8. closing 时序协议（v2.1 §6.3，I5 固化防 plan 过期卡死；v0.49.0 §83.3 修订）
 
-**顺序不可乱**——tasks.md 翻转/矩阵回灌改变 artifacts_hash → plan 过期（receipt 失效）；必须先 refresh-hash 再记录 review：
+**顺序不可乱**——矩阵回灌（改写 execution-contract.md 的 `## Test Matrix` 段）改变 contract_hash → plan 过期；必须先 refresh-hash 再记录 review：
 
 ```
 run 终局 PASS
   → 矩阵回灌（test-matrix-export v2 + 覆盖 test-matrix.md）
   → tf state rebuild（只改 state 文件，不动 plan JSON）
-  → tf execution refresh-hash（更新 plan.artifacts_hash，防 plan 过期）
+  → tf execution refresh-hash（同步 plan 与内嵌 recommendation_receipt 的制品 hash）
   → 委托代理 commit glaf4-dev 产物
   → code-reviewer 独立审查 base..head（报告落 .superpowers/sdd/reviews/）
   → tf execution review --wave w1 --verdict pass
@@ -130,3 +130,5 @@ run 终局 PASS
 ```
 
 > `tf state rebuild` 不能替代 `refresh-hash`（前者不动 plan JSON）；review 需真实 git base≠head，必须 commit 后取 SHA。
+>
+> **v0.49.0 §83.3 变更**：① tasks.md 勾选回写不再改变 artifacts_hash（§83.3.1），勾选可与 receipt 登记同轮；② receipt 有效性判据改为 wave 定义指纹（§83.3.2）——refresh-hash / revise 不再失效已有 pass receipt；③ refresh-hash 同步内嵌 recommendation_receipt，命令在其目标场景下可用（§83.3.3）。

package/skills/release-archivist/SKILL.md

@@ -161,7 +161,7 @@ Merge change-level architecture artifacts to the global `docs/architecture/` bas
 tf arch-merge <change-dir>
 ```
 
-This merges `architecture/{architecture,database,api}.md` and `architecture/sql/` into the global architecture docs. Skip silently when `architecture/` does not exist (architecture-design was `skipped`).
+This merges `architecture/{architecture,database,api}.md` and `architecture/sql/` into the global architecture docs. Skip silently when `architecture/` does not exist (architecture-design was `skipped`) — 前置判据见 `## Lightweight Closure > 回写链前置判据`（v0.22 §87：先判断再决定是否执行命令）。
 
 **Execution order (mandatory, v0.12 §43.4)**: `arch-merge` → `prototype-sync` → `test-merge` → `compound promotion`. Do not parallelise — global docs must not be in a half-updated state.
 
@@ -193,7 +193,7 @@ This merges `test-matrix.md` into `docs/test-ledger/`:
 - **appendChangelog**: archive test-matrix.md → `changelog/{change-id}.md`
 - **rewriteIndex**: recalculate module/case/deferred counts, rewrite `INDEX.md`
 
-Skip silently when `test-matrix.md` does not exist (legacy change or test_matrix_skipped=true).
+Skip silently when `test-matrix.md` does not exist (legacy change or test_matrix_skipped=true) — 前置判据见 `## Lightweight Closure > 回写链前置判据`（v0.22 §87：先判断再决定是否执行命令）。
 
 **Execution verification**: check stdout output for `test-merge complete` confirmation. If the command did not execute or failed, Step 5 Report's `Test Matrix` row (from Step 2b) must note the reason.
 
@@ -205,13 +205,13 @@ During closing, promote change-level learnings to the global solutions library:
 tf solutions promote <change-dir>
 ```
 
-This checks `specs/<cap>/learnings.md` for entries meeting promotion criteria:
+This checks the change's `learnings.md` (change root; v0.49.0 §83.3.5 path unification) for entries meeting 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
 
 Report promotion results in the closing summary. Promotion is advisory — failures do not block closing.
 
-### Compound Capture Check (v0.5)
+### Compound Capture Check (v0.5；v0.49.0 §83.3.5 明确写入方)
 
 Before finalizing the closing, check if this change produced any learnable moments:
 
@@ -220,15 +220,14 @@ Before finalizing the closing, check if this change produced any learnable momen
 - Did scope expand beyond the original proposal?
 - Did execution-contract drift from proposal?
 
-If any of the above occurred, capture the learning:
-```bash
-tf solutions capture \
-  --phase cross-phase --domain <domain> --type pitfall \
-  --severity medium --summary "<what happened and how to prevent it>"
-```
+If any of the above occurred, **write them to the change's `learnings.md` (change root)** — one `## <title>` entry per learning, each carrying a frontmatter block (`phase` / `domain` / `type` / `severity` / `date`). Format reference: `tf runtime asset read templates/learnings.md`. This is the file the `compound-captured` guard checks and `tf solutions promote` reads; entries without frontmatter are skipped by promote (reason listed in its output).
+
+`tf solutions capture` writes to global `docs/solutions/` — it does **not** create `learnings.md`. Use it only for product-level learnings that belong directly in the global library.
 
 This check is advisory — skip silently if no learnable moments are detected.
 
+> 详细收尾流程（Prototype Sync / Compound Promotion / Compound Capture / Worktree Deisolation / Code Landing）见 `references/closing-procedures.md`。
+
 ### 阶段产物同步门禁点（v0.37.0 §68.2 G5）
 
 回写链（arch-merge → prototype-sync → test-merge → compound promotion）全部完成后、`tf state transition closing` 之前，**阻塞确认**（AskUserQuestion）是否同步 change 实施结果（团队协作：落地结果是团队最需要看的内容）：
@@ -267,6 +266,15 @@ This check is advisory — skip if the user declines. If the user reports issues
 
 Verify files exist and are non-empty, run `node --check` on code files, skip 5-step verification. Still record DP-6 and DP-7.
 
+**回写链前置判据（v0.22 §87）**：先按下表判断适用性，**不适用则不执行命令**（v0.22 实测：逐项跑完才知道不适用，占 release-archivist 80% 耗时）。本表 4 行判据**仅在 Lightweight Closure 适用**；其中 arch-merge 与 test-merge 两行的 "Skip silently" 见 `### Architecture Merge`（:164 正文句）与 `### Test Merge`（:196 正文句）。
+
+| 回写项 | 前置判据 | 不满足时登记 |
+|---|---|---|
+| arch-merge | `test -d <change-dir>/architecture/` | `skipped` |
+| prototype-sync | 契约含 `## UX 增量` 段 | `no UX delta` |
+| test-merge | `test -f <change-dir>/test-matrix.md` | `skipped` |
+| compound promotion | `test -f <change-dir>/learnings.md` | `no learnings` |
+
 **⚠️ tests-passing 门禁不因轻量收尾而豁免（v0.13 §50）**：hotfix/tweak 的 `executing→closing` guard 同样挂 `tests-passing`。非存量 change 仅记 DP-6/DP-7 不足以放行——必须二选一：① `test_matrix_skipped=true` + `test_matrix_skip_reason` 已由 contract-builder 设置（hotfix/tweak 常规路径，先 `tf state get` 核实）；② 有代码变更时补跑测试套件并 `tf test record <change-dir> --from <输出>`。
 
 ## Exception Handling

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

@@ -30,7 +30,7 @@ Promotion criteria:
 
 Report promotion results in the closing summary. Promotion is advisory — failures do not block closing.
 
-## Compound Capture Check (v0.5)
+## Compound Capture Check (v0.5；v0.49.0 §83.3.5 明确写入方)
 
 Before finalizing the closing, check if this change produced any learnable moments:
 
@@ -39,12 +39,17 @@ Before finalizing the closing, check if this change produced any learnable momen
 - Did scope expand beyond the original proposal?
 - Did execution-contract drift from proposal?
 
-If any occurred, capture the learning:
+If any occurred, **write them to the change's `learnings.md` (change root)** — one `## <title>` entry per learning, each carrying a frontmatter block (`phase` / `domain` / `type` / `severity` / `date`). Format reference: `tf runtime asset read templates/learnings.md`. This is the file the `compound-captured` guard checks and `tf solutions promote` reads; entries without frontmatter are skipped by promote (reason listed in its output).
+
+**条目质量**：写「正确做法」前先验证它在系统层面成立——局部观察得出的 workaround 若被沉淀为通则，会被后续 change 当经验复用，反而固化缺陷（v0.49.0 §83.2.2 实证）。
+
+For product-level learnings that belong directly in the global library (not change-scoped):
 ```bash
 tf solutions capture \
   --phase cross-phase --domain <domain> --type pitfall \
   --severity medium --summary "<what happened and how to prevent it>"
 ```
+`tf solutions capture` writes to global `docs/solutions/` — it does **not** create `learnings.md`.
 
 Advisory — skip silently if no learnable moments detected.
 

package/skills/workflow-start/SKILL.md

@@ -87,7 +87,7 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 
 > **⛔ 串行约束（v0.30.0）**：四步严格串行。**修复子代理（architecture-design）完成前 MUST NOT dispatch 审查子代理（architecture-reviewer）**——并行会使审查跑在修复之前、误报"全部未修复"FAIL（来源：workflow-feedback 2026-08-01）。并行白名单：仅多个独立 change 的工作可并行；修复→审查、设计→审查必须串行。
 
-1. **Dispatch**: `architecture-design` as sub-agent（**输入含 `docs/architecture/iterations/<vN>/architecture.md` 产品级架构快照**，v0.36.0——变更级只引用产品级聚合注册表，不重定义）→ returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
+1. **Dispatch**: 先跑 `tf arch precheck <change-dir> --json`（v0.22 §88.3.2：确定性证据工具，正常调用退出码恒 0；`signal: none` 时子代理走 Fast Path，只读 brief + precheck 输出）→ dispatch `architecture-design` as sub-agent（**输入含 `docs/architecture/iterations/<vN>/architecture.md` 产品级架构快照**，v0.36.0——变更级只引用产品级聚合注册表，不重定义；**Fast Path 命中时不传快照**）→ returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
 2. **Auto-review** (decision=required 时触发): 校验产物文件存在且非空 → dispatch `architecture-reviewer` sub-agent（**记录子代理 ID**，agent 会直接写审查报告到 `changes/<name>/architecture/auto-review.md`）→ FAIL 则通过 **SendMessage 恢复原 architecture-design 子代理**修正（≤3 轮 + 收敛检测，不收敛转人工）
 3. **Reasonableness check + state write**: PASS/PASS_WITH_WARNINGS → write `arch_design_decision` + `arch_review_*` to yaml; skipped + brief 含架构关键词 → BLOCK; required + artifacts 缺失 → BLOCK; required + auto-review FAIL → BLOCK
 4. **DP-A 用户确认门（v0.29.0 §37）**: 输出架构决策摘要 → AskUserQuestion 确认 → 需要调整时**必须通过 SendMessage 恢复原子代理**修改（禁止主代理直接修改，禁止启动新子代理）→ 修改后 SendMessage 恢复原 reviewer 重新 auto-review → 回到本步骤重新确认。含项目规范变更提示（advisory）。详见 `references/routing-rules.md`「Step 4: DP-A」
@@ -114,6 +114,7 @@ Contract exists and approved, contract matches artifacts. Include `DP-4: 执行
 2. 对每个 wave：
    - dispatch build-executor 执行当前 wave
    - 等待 build-executor 完成（task-notification）
+   - **确认该 wave 的 tasks.md 勾选已回写**（v0.49.0 §83.3.4）：build-executor 的 wave 完成协议包含回写；未回写则 SendMessage 让其补做。`tasks-complete` 在 closing 强制要求零未勾选项，留到收尾轮必然遗忘
    - dispatch code-reviewer 审查当前 wave
    - 等待 review receipt + verdict=pass
 3. 所有 wave 完成后，继续下一步路由
@@ -131,7 +132,7 @@ Contract exists and approved, contract matches artifacts. Include `DP-4: 执行
 Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.
 
 ### Route to code-reviewer
-The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
+The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition. **`--report` 必须落在 change review overlay 内**（`<change-dir>/.superpowers/sdd/reviews/`，v0.22 §86）——其他路径被 CLI 拒绝（`execution-plan.mjs` 的 `validateReviewReportEvidence`）；派发审查子代理时直接给 overlay 路径，避免"任务指令写 `reviews/`、CLI 只认 overlay"导致的双写副本。
 
 **v0.39.0 主动串行编排**：workflow-start 在每个 wave 完成后主动 dispatch code-reviewer，而不是等待 build-executor 完成所有 wave。这是 workflow-start 的编排责任，不是 build-executor 的责任。
 
@@ -166,10 +167,20 @@ work.
 
 ### Fast-Path Routing
 
-**DP-0 处理**（v0.22.5 F03 修复）：hotfix/tweak 路径隐式跳过 DP-0（`dp_0_confirmed` 保持 `null`），因为意图已明确（修复/微调），无需从零探索。contract-builder 的 DP-3 审批成为唯一门禁。
+**DP-0 处理**（v0.22.5 F03；**v0.22 §88 修正**）：hotfix/tweak 路径**仍执行 DP-0**（快速形态：确认 scope / 约束 / AC / 沟通偏好，不重新问"你想做什么"）——实测 H1 的 `dp_0_decisions` 承载了后续契约与实施的全部基线（scope/约束/AC/模式/沟通偏好），隐式跳过会使该信息无处安放；`arch_design_decision == skipped` 时 DP-0 可与 DP-A 合并为一次确认（见下「确认点合并」）。contract-builder 的 DP-3 审批仍是唯一硬门禁。
 
-- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
-- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
+**确认点合并（v0.22 §88.3.1）**：为减少用户交互轮次，以下三组可合并为**一次** AskUserQuestion。**门禁强度不变**——`dp_0_confirmed` / `dp_a_result` / `dp_3_result` / `dp_4_result` 仍须写入，guard 维度（`dp3-approved` / `execution-plan-ready`）不豁免：
+
+| 合并组 | 触发条件 | 合并后形态 |
+|---|---|---|
+| DP-0 + DP-A | `arch_design_decision == skipped` | 一次「变更基线确认」：brief 继承 + 架构判定结果 |
+| DP-3 + G4 + DP-4 | 契约已产出且 hash 有效 | 一次「实施授权确认」：批准契约 + 同步选择 + 执行模式 |
+| DP-7 + 代码落地 + G5 | 恒成立 | 一次「归档确认」 |
+
+**不合并**：`arch_design_decision == required` 时 DP-A 必须独立——用户需单独审架构产物。
+
+- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **`tasks.md` 不得静默缺失（v0.22 §85）**：hotfix 默认不产出该文件，但必须由 contract-builder 显式登记 `tasks_skipped=true` + `tasks_skip_reason`（或一并产出最小任务清单，归属 contract-builder）——`tasks-complete` 在 closing 考核该维度，静默缺失会死锁（修复前即此状态）。**architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
+- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **`tasks.md` 须显式 skip（v0.22 §85）**：tweak 跳过 spec-writer 与 contract-builder，故既无原生 `tasks.md` 也无人代写——由**主代理**经 `tf state set` 写入 `tasks_skipped=true` + `tasks_skip_reason`（`tf state set` 是 CLI 调用，不违反 Artifact Ownership 的 Edit/Write 禁令），否则 `tasks-complete` 在 closing 死锁。tweak 的 `executing:closing` 不含 `test-matrix-complete`（`guard.mjs:82`），矩阵豁免非 guard 必需。**architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
 
 Post-transition: 💡 `tf inject <change-dir>` to update phase-guard artifacts.
 
@@ -237,7 +248,7 @@ build-executor 修复 findings 后，workflow-start 必须：
 - **No routing to spec-writer without architecture-design gate pass** (v0.9 §26): `arch_design_decision` must be `required` or `skipped` (not `null`). hotfix/tweak 不豁免
 - **No arch state write without auto-review PASS** (v0.28.1 §36): when `decision: required`, auto-review MUST complete with PASS or PASS_WITH_WARNINGS before writing `arch_design_decision` to yaml. FAIL → loop fix (≤3 rounds) or escalate to human
 - **No routing past DP-A without user confirmation** (v0.29.0 §37): architecture-design 四步协议完成后，必须经 DP-A 用户确认门（AskUserQuestion）才能路由到 spec-writer。用户选择"需要调整"时，修改必须通过子代理执行，修改后重新 auto-review + 重新 DP-A 确认
-- **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37): 子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`，build-executor → 代码文件）。主代理（workflow-start）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。**v0.39.0 强化**：主代理 MUST NOT 直接 Edit/Write 任何文件 under `changes/<name>/` 或 `.worktrees/`——无论改动量大小，必须通过 SendMessage 委托子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证
+- **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37): 子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`，build-executor → 代码文件）。**tasks.md 的勾选状态属执行期写入区**（v0.49.0 §83.3.4）：任务文本归 spec-writer，勾选标记由 build-executor 在 wave 完成时回写（主代理只检查不代写）。**hotfix/tweak 路径的 tasks.md 归属 contract-builder**（v0.22 §85）：该路径跳过 spec-writer，若 change 需要任务记录则由 contract-builder 一并产出；默认路径是显式跳过（`tasks_skipped=true` + `tasks_skip_reason`——hotfix 由 contract-builder 写入，tweak 由主代理写入）。主代理（workflow-start）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。**v0.39.0 强化**：主代理 MUST NOT 直接 Edit/Write 任何文件 under `changes/<name>/` 或 `.worktrees/`——无论改动量大小，必须通过 SendMessage 委托子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证
 - **修复后必须 re-review** (v0.39.0): build-executor 修复 findings 后，workflow-start 必须 dispatch code-reviewer re-review 确认修复有效，记录 review receipt（verdict=pass）。禁止在 review receipt 未记录或 verdict!=pass 时进入下一阶段
 - **No cross-change artifact modification (v0.30.0)**: 处理 change X 时 **MUST NOT** 编辑 `changes/Y/`（Y≠X）下任何产物。发现跨 change 依赖/问题时：① 在 change X 的 ADR/proposal 中显式声明依赖；② change Y 进入 workflow-start 时，扫描是否有其他 change 声明了对 Y 的依赖并提醒用户；③ change Y 的产物修改必须走 Y 自己的完整流程（architecture-design → auto-review → DP-A），不得绕过。跨 change 一致性核查可调度 `cross-change-consistency-checker` agent（来源：workflow-feedback 2026-08-01）
 
@@ -254,7 +265,8 @@ workflow-start 负责写入以下字段到 `.team-flow.yaml`：
 - `dp_1_*`：need-explorer 完成后的需求澄清决策
 - `dp_2_*`：spec-writer 完成后的规格决策
 - `dp_3_*`：contract-builder 完成后的契约决策
-- `dp_5_*`：build-executor 执行决策 / bug-investigator 调试决策（共享 dp_5；dp_4 预留未用）
+- `dp_4_*`：执行模式选择（由 `tf execution plan --confirm` 程序化写入，不在 SETTABLE_FIELDS；`execution-plan-ready` 维度校验其指向当前 plan revision）
+- `dp_5_*`：build-executor 执行决策 / bug-investigator 调试决策
 - `dp_6_*`：release-archivist 完成后的验证决策
 - `dp_7_*`：release-archivist 归档确认决策
 

package/skills/workflow-start/references/routing-rules.md

@@ -13,6 +13,8 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 
 ### Step 1: Dispatch architecture-design sub-agent
 
+**先跑证据工具（v0.22 §88.3.2）**：`tf arch precheck <change-dir> --json` —— 输出确定性证据（架构关键词的变更语境命中 / 否定命中 / 仅提及 + 改动文件分类），退出码恒 0。`signal: none` → 子代理走 Fast Path（只读 brief + precheck 输出，不读全量 `docs/architecture/`）；`weak` / `strong` → 完整路径。判断权在子代理，precheck 只用于缩小输入范围。
+
 Dispatch `architecture-design` as sub-agent with inputs:
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段
@@ -228,7 +230,7 @@ Guard: `... check <dir> approved-for-build executing --json` → fail = BLOCK.
 Execution hit blockage: test failure, unexpected behavior, build error. After debugging, route back to build-executor.
 
 ## Route to code-reviewer
-Current planned wave implemented and ready for review. Reviewer must write:
+Current planned wave implemented and ready for review. Reviewer must write the report **inside the change review overlay** `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: other paths are rejected by the CLI), then record:
 ```bash
 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>
 ```

package/templates/learnings.md

@@ -0,0 +1,51 @@
+# Session Learnings — <change-name>
+
+> change 级经验台账（**change 根目录 `learnings.md`**）。
+>
+> **位置权威（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`（各阶段入口注入）。
+>
+> **晋升前提**：只有带完整 frontmatter 的条目才会被晋升。缺字段时按默认 `severity=low` / `type=insight` 处理，不满足晋升条件即跳过——promote 会在输出中列出跳过原因，不再静默。
+>
+> **注意**：`tf solutions capture` 写入的是全局 `docs/solutions/`，**不会**创建本文件。
+
+## 1. <条目标题：一句话说清问题或模式>
+
+---
+phase: cross-phase        # 阶段名（prd/plan/architecture/prototype/spec/build/review/cross-phase）或具体领域阶段
+domain: <领域>            # 如 jest / sdd / spring-boot；注入时按领域过滤
+type: pitfall             # pitfall | pattern | insight
+severity: medium          # high | medium | low
+date: YYYY-MM-DD
+---
+
+- **教训来源**：<具体事件——哪个 wave / 哪条命令 / 什么现象>
+- **正确做法**：<可执行的行动，而非泛泛原则>
+- **边界**：<什么情况下不适用；避免把局部观察当通则>
+
+## 2. <下一条目>
+
+---
+phase: cross-phase
+domain: <领域>
+type: pattern
+severity: high
+date: YYYY-MM-DD
+---
+
+- **教训来源**：...
+- **正确做法**：...
+- **边界**：...
+
+---
+
+## 晋升条件（`tf solutions promote`）
+
+| 条件 | 行为 |
+|---|---|
+| `severity` ≥ medium 且 `type` = pitfall / pattern | 晋升到全局 `docs/solutions/<phase>/`，并追加 INDEX 行 |
+| 与全局 INDEX 已有条目 domain + type 匹配 | 不新建文件：升级已有条目 severity（low→medium→high）+ 条目 frontmatter `confirmed` 计数 +1 + 更新 INDEX 行 |
+| 其他 | 保留在本文件；promote 输出中列为 skipped 并附原因 |
+
+**条目质量要求**：写「正确做法」前先验证它在系统层面成立——局部观察得出的 workaround 若被沉淀为通则，会被后续 change 当经验复用，反而固化缺陷（v0.49.0 §83.2.2 的实证教训）。

package/docs/solutions/cross-phase/2026-07-28-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-07-28
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-07-29-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-07-29
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-07-30-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-07-30
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-07-31-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-07-31
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-01-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-01
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-03-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-03
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-04-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-04
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-05-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-05
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-06-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-06
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-07-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-07
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-17-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-17
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-18-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-18
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-19-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-19
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）

package/docs/solutions/cross-phase/2026-08-21-no-summary.md

@@ -1,17 +0,0 @@
----
-phase: cross-phase
-domain: general
-type: insight
-severity: medium
-date: 2026-08-21
-source: 
----
-
-## 问题描述
-(no summary)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）