@xulthekl/team-flow 0.48.0 → 0.49.0

package/scripts/lib/solutions-index-gen.mjs

@@ -15,6 +15,7 @@
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const PHASES = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
@@ -104,7 +105,7 @@ export function run(args = {}) {
 }
 
 // CLI 直接执行
-if (process.argv[1]?.includes('solutions-index-gen')) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = {};
   const dirIdx = process.argv.indexOf('--dir');
   if (dirIdx > -1 && process.argv[dirIdx + 1]) args.dir = process.argv[dirIdx + 1];

package/scripts/lib/solutions-inject.mjs

@@ -14,6 +14,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 
@@ -66,7 +67,7 @@ export function run(args = {}) {
   return { entries: top5 };
 }
 
-if (process.argv[1]?.includes('solutions-inject')) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = {};
   for (let i = 2; i < process.argv.length; i += 2) {
     const key = process.argv[i]?.replace('--', '');

package/scripts/lib/solutions-promote.mjs

@@ -6,7 +6,8 @@
  * 用法：tf solutions promote <change-dir> [--dir <solutions-dir>]
  *
  * 功能：
- * 1. 读取 specs/<cap>/learnings.md
+ * 1. 读取 change 根 learnings.md（v0.49.0 §83.3.5：统一路径——此前注释误写 specs/<cap>/，
+ *    与本文件第 58 行的实际实现及 compound-captured guard 均不一致）
  * 2. 逐条检查晋升条件（severity ≥ medium 且 type = pitfall/pattern）
  * 3. 检查与全局 INDEX 是否重复（domain+type 匹配）
  * 4. 符合条件 → 写入全局 docs/solutions/
@@ -19,6 +20,7 @@
 
 import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 function parseFrontmatter(content) {
   // learnings.md 中每个条目以 `## 标题` 开头，frontmatter 紧跟标题行之后；
@@ -43,7 +45,59 @@ function parseLearnings(content) {
     const title = lines[0]?.trim() || '';
     const fm = parseFrontmatter(s);
     return { title, fm, body: s.trim() };
-  }).filter(e => e.title && e.title !== 'Learnings');
+  // v0.49.0 §83.3.5：排除文件级标题（`# Session Learnings` 会被 split 成首个 section），
+  // 否则它会被当成一条无 frontmatter 的条目计入 skipped
+  }).filter(e => e.title && e.title !== 'Learnings' && !e.title.startsWith('#'));
+}
+
+/**
+ * v0.49.0 §83.3.5：把解析出的条目重整为可写入全局文件的形式 ——
+ * ① 补回 `## ` 标题前缀（parseLearnings 按 `^## ` 分割，body 首行不含标记）
+ * ② 剔除 body 中已含的原 frontmatter 块（原实现直接写 body → 产出双 frontmatter）
+ */
+function renderEntryBody(learning) {
+  const body = learning.body
+    .replace(/^[^\n]*\n?/, '')
+    .replace(/(?:^|\n)---\n[\s\S]*?\n---[ \t]*\n?/, '\n')
+    .trim();
+  return `## ${learning.title}\n\n${body}`;
+}
+
+const SEVERITY_LADDER = { low: 'medium', medium: 'high' };
+
+/**
+ * v0.49.0 §83.3.5：重复命中时按 promotion-rules.md 承诺真正落盘（原实现只 `updated++`，
+ * 不更新 INDEX 行、不标记条目）——升级 INDEX 行 severity + 条目文件 confirmed 计数。
+ */
+function confirmExistingEntry(solutionsDir, indexContent, domain, type) {
+  const lines = indexContent.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    // INDEX 列：| date | phase | domain | type | severity | summary | file |
+    const cols = lines[i].split('|').map(column => column.trim());
+    if (cols.length < 9 || cols[3] !== domain || cols[4] !== type) continue;
+
+    const currentSeverity = cols[5];
+    const nextSeverity = SEVERITY_LADDER[currentSeverity] ?? currentSeverity;
+    if (nextSeverity !== currentSeverity) {
+      lines[i] = lines[i].replace(`| ${currentSeverity} |`, `| ${nextSeverity} |`);
+    }
+    markEntryConfirmed(join(solutionsDir, cols[7]));
+    return { indexContent: lines.join('\n'), from: currentSeverity, to: nextSeverity, file: cols[7] };
+  }
+  return null;
+}
+
+function markEntryConfirmed(filePath) {
+  if (!existsSync(filePath)) return;
+  const content = readFileSync(filePath, 'utf-8');
+  const block = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!block) return;
+  const counter = block[1].match(/^confirmed:\s*(\d+)\s*$/m);
+  const next = counter ? parseInt(counter[1], 10) + 1 : 2;
+  const frontmatter = counter
+    ? block[1].replace(/^confirmed:\s*\d+\s*$/m, `confirmed: ${next}`)
+    : `${block[1]}\nconfirmed: ${next}`;
+  writeFileSync(filePath, content.replace(block[0], `---\n${frontmatter}\n---`), 'utf-8');
 }
 
 export function run(args = {}) {
@@ -58,7 +112,7 @@ export function run(args = {}) {
   const learningsPath = join(changeDir, 'learnings.md');
   if (!existsSync(learningsPath)) {
     console.log(`No learnings.md found in ${changeDir}, nothing to promote`);
-    return { promoted: 0, updated: 0 };
+    return { promoted: 0, updated: 0, skipped: 0 };
   }
 
   const content = readFileSync(learningsPath, 'utf-8');
@@ -66,15 +120,17 @@ export function run(args = {}) {
 
   if (learnings.length === 0) {
     console.log('No learning entries found');
-    return { promoted: 0, updated: 0 };
+    return { promoted: 0, updated: 0, skipped: 0 };
   }
 
   // 读取全局 INDEX
   const indexPath = join(solutionsDir, 'INDEX.md');
-  const indexContent = existsSync(indexPath) ? readFileSync(indexPath, 'utf-8') : '';
+  let indexContent = existsSync(indexPath) ? readFileSync(indexPath, 'utf-8') : '';
 
   let promoted = 0;
   let updated = 0;
+  // v0.49.0 §83.3.5：跳过原因可见化（原实现静默 continue，用户看不出为什么一条都没晋升）
+  const skipped = [];
 
   for (const learning of learnings) {
     const severity = learning.fm?.severity || 'low';
@@ -85,12 +141,27 @@ export function run(args = {}) {
     // 晋升条件：severity ≥ medium 且 type = pitfall/pattern
     const sevOk = severity === 'high' || severity === 'medium';
     const typeOk = type === 'pitfall' || type === 'pattern';
-    if (!sevOk || !typeOk) continue;
+    if (!sevOk || !typeOk) {
+      skipped.push({
+        title: learning.title,
+        reason: learning.fm
+          ? `severity=${severity}, type=${type}（需 severity ≥ medium 且 type = pitfall|pattern）`
+          : 'no frontmatter（缺 severity/type，按默认 low/insight 处理）',
+      });
+      continue;
+    }
 
     // 检查重复：domain+type 匹配
     const dupRegex = new RegExp(`\\| ${domain} \\| ${type} \\|`);
     if (dupRegex.test(indexContent)) {
-      console.log(`Duplicate found (${domain}/${type}), marking as confirmed pattern`);
+      const outcome = confirmExistingEntry(solutionsDir, indexContent, domain, type);
+      if (!outcome) {
+        skipped.push({ title: learning.title, reason: `duplicate ${domain}/${type} 但 INDEX 行无法定位` });
+        continue;
+      }
+      indexContent = outcome.indexContent;
+      writeFileSync(indexPath, indexContent, 'utf-8');
+      console.log(`Confirmed: ${domain}/${type} severity ${outcome.from} → ${outcome.to}（${outcome.file}）`);
       updated++;
       continue;
     }
@@ -115,22 +186,29 @@ date: ${date}
 source: ${basename(changeDir)}
 ---
 
-${learning.body}
+${renderEntryBody(learning)}
 `;
     writeFileSync(filePath, fileContent, 'utf-8');
 
     // 追加 INDEX
-    appendFileSync(indexPath, `| ${date} | ${phase} | ${domain} | ${type} | ${severity} | ${learning.title.slice(0, 80)} | ${phase}/${fileName} |\n`, 'utf-8');
+    const indexRow = `| ${date} | ${phase} | ${domain} | ${type} | ${severity} | ${learning.title.slice(0, 80)} | ${phase}/${fileName} |\n`;
+    appendFileSync(indexPath, indexRow, 'utf-8');
+    indexContent += indexRow;
 
     console.log(`Promoted: ${phase}/${fileName}`);
     promoted++;
   }
 
-  console.log(`\nPromotion complete: ${promoted} promoted, ${updated} updated as confirmed`);
-  return { promoted, updated };
+  // v0.49.0 §83.3.5：解析/晋升/确认/跳过汇总（原实现只报 promoted/updated）
+  console.log(`\nPromotion complete: ${promoted} promoted, ${updated} confirmed, ${skipped.length} skipped`);
+  if (skipped.length > 0) {
+    console.log('Skipped entries:');
+    for (const item of skipped) console.log(`  - ${item.title}: ${item.reason}`);
+  }
+  return { promoted, updated, skipped: skipped.length };
 }
 
-if (process.env.NODE_ENV !== 'test' && process.argv[1]?.includes('solutions-promote')) {
+if (process.env.NODE_ENV !== 'test' && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = { _: [] };
   for (let i = 2; i < process.argv.length; i++) {
     if (process.argv[i].startsWith('--')) {

package/scripts/lib/test-record.mjs

@@ -33,30 +33,54 @@ export function parseMavenSurefire(text) {
   return { total, passed: total - failures - errors - skipped, failed: failures + errors, skipped };
 }
 
-/** maven surefire XML 报告目录（target/surefire-reports）：累加 <testsuite> 属性。 */
-export function parseSurefireReportDir(dir) {
+/**
+ * 通用 junit XML 解析：累加 <testsuite> 的 tests/failures/errors/skipped 属性。
+ *
+ * v0.49.0 §83.3.6（来源：workflow-feedback 20260909）：maven-surefire 与 pytest 的
+ * junit XML 结构同构（<testsuites>/<testsuite>）。此前该逻辑只服务 maven-surefire，
+ * pytest runner 只认 terminal summary —— 同一 CLI 对不同 runner 的结构化支持不对称。
+ */
+export function parseJunitXml(text) {
   let total = 0; let failures = 0; let errors = 0; let skipped = 0;
   let found = false;
-  for (const name of readdirSync(dir)) {
-    if (!name.endsWith('.xml')) continue;
-    const content = readFileSync(join(dir, name), 'utf-8');
-    for (const tag of content.matchAll(/<testsuite\b[^>]*>/g)) {
-      const attrs = tag[0];
-      const pick = (key) => {
-        const am = attrs.match(new RegExp(`\\b${key}="(\\d+)"`));
-        return am ? parseInt(am[1], 10) : 0;
-      };
-      found = true;
-      total += pick('tests');
-      failures += pick('failures');
-      errors += pick('errors');
-      skipped += pick('skipped');
-    }
+  for (const tag of text.matchAll(/<testsuite\b[^>]*>/g)) {
+    const attrs = tag[0];
+    const pick = (key) => {
+      const am = attrs.match(new RegExp(`\\b${key}="(\\d+)"`));
+      return am ? parseInt(am[1], 10) : 0;
+    };
+    found = true;
+    total += pick('tests');
+    failures += pick('failures');
+    errors += pick('errors');
+    skipped += pick('skipped');
   }
   if (!found) return null;
   return { total, passed: total - failures - errors - skipped, failed: failures + errors, skipped };
 }
 
+/** junit XML 内容特征（用于嗅探；只检查头部，避免大报告全量扫描）。 */
+function looksLikeJunitXml(text) {
+  return /<testsuites?\b/.test(text.slice(0, 512));
+}
+
+/** maven surefire XML 报告目录（target/surefire-reports）：累加目录内所有 XML。 */
+export function parseSurefireReportDir(dir) {
+  let aggregated = null;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.xml')) continue;
+    const parsed = parseJunitXml(readFileSync(join(dir, name), 'utf-8'));
+    if (!parsed) continue;
+    aggregated = aggregated === null ? parsed : {
+      total: aggregated.total + parsed.total,
+      passed: aggregated.passed + parsed.passed,
+      failed: aggregated.failed + parsed.failed,
+      skipped: aggregated.skipped + parsed.skipped,
+    };
+  }
+  return aggregated;
+}
+
 /** jest --json 输出。 */
 export function parseJest(text) {
   let data;
@@ -69,8 +93,18 @@ export function parseJest(text) {
   return { total, passed, failed, skipped };
 }
 
-/** pytest terminal summary："== 5 passed, 2 failed, 1 skipped in 3.21s ==" */
+/**
+ * pytest 输出：junit XML（`--junitxml=<path>`）或 terminal summary
+ * （"== 5 passed, 2 failed, 1 skipped in 3.21s =="）。
+ *
+ * v0.49.0 §83.3.6：XML 优先 —— 结构稳定，不受 `-q`/`-v`/颜色码/`--tb` 影响，
+ * 且 CI 流水线天然产出 XML（来源：workflow-feedback 20260909）。
+ */
 export function parsePytest(text) {
+  if (looksLikeJunitXml(text)) {
+    const xml = parseJunitXml(text);
+    if (xml) return xml;
+  }
   const lines = text.split('\n');
   const summaryLine = [...lines].reverse().find(l => /=+\s.*(passed|failed|error|no tests ran)/.test(l));
   if (!summaryLine) return null;
@@ -142,9 +176,16 @@ export function classifyFailure(text) {
   return 'unknown';
 }
 
-/** auto 识别：按内容特征匹配 runner。 */
+/**
+ * auto 识别：按内容特征匹配 runner。
+ *
+ * v0.49.0 §83.3.6：junit XML 特征优先嗅探。surefire 与 pytest 的 XML 同构，auto 模式
+ * 统一归入 maven-surefire（解析结果相同）；需要把 runner 记为 pytest 时显式传
+ * `--runner pytest`（同样支持 XML）。
+ */
 export function detectRunner(text) {
   const trimmed = text.trim();
+  if (looksLikeJunitXml(trimmed) && parseJunitXml(trimmed)) return 'maven-surefire';
   if (trimmed.startsWith('{') && parseJest(trimmed)) return 'jest';
   if (/Tests run:\s*\d+,\s*Failures:/.test(trimmed)) return 'maven-surefire';
   if (parsePytest(trimmed)) return 'pytest';
@@ -164,7 +205,8 @@ export async function run(args) {
     allowPositionals: true,
   });
 
-  const usageMsg = 'Usage: tf test record <change-dir> --from <runner-output-file|surefire-report-dir> [--runner auto|maven-surefire|jest|pytest] [--json]';
+  const usageMsg = 'Usage: tf test record <change-dir> --from <runner-output-file|surefire-report-dir> [--runner auto|maven-surefire|jest|pytest] [--json]\n'
+    + '  maven-surefire: console summary, surefire XML dir/file;  pytest: terminal summary or junit XML (--junitxml);  jest: --json';
   if (positionals[0] !== 'record') {
     console.error(usageMsg);
     process.exit(2);
@@ -222,7 +264,11 @@ export async function run(args) {
     stats = PARSERS[runner](text);
   }
   if (!stats) {
-    console.error(`Could not parse ${runner} output in ${fromPath} — no recognizable test summary found.`);
+    // v0.49.0 §83.3.6：错误信息附输入形态指引（原提示对"传了 XML"的用户无帮助）
+    const hint = runner === 'pytest'
+      ? 'pytest accepts a terminal summary or a junit XML report (pytest --junitxml=<path>).'
+      : `Supported runners: ${SUPPORTED_RUNNERS.join(', ')} (or pass --runner explicitly).`;
+    console.error(`Could not parse ${runner} output in ${fromPath} — no recognizable test summary found.\n${hint}`);
     process.exit(1);
   }
 

package/skills/build-executor/SKILL.md

@@ -11,6 +11,8 @@ Controls the implementation phase. Uses `execution-contract.md` as the workflow
 
 Read: `execution-contract.md`, `tasks.md`, relevant `specs/`, relevant `design.md`. (Skip contract/spec requirements when workflow is `tweak`.)
 
+**复利经验注入（v0.49.0 §83.3.5）**：运行 `tf solutions inject --phase cross-phase`（失败静默）——注入 `docs/solutions/` 中跨阶段可复用的历史经验（踩坑/模式），供实施时规避已知问题。注入内容是**经验提示而非约束**：与当前 change 的契约/规格冲突时以契约/规格为准，并把冲突回报给 workflow-start。
+
 When `architecture/sql/` exists, also read:
 - `architecture/sql/ddl/*.sql` — executable DDL scripts; reference directly for DB schema change tasks instead of hand-writing DDL
 - `architecture/sql/migration/*.sql` — data migration scripts; execute as-is for data transformation tasks
@@ -95,7 +97,7 @@ The recommendation uses task count, configured `execution.inlineThreshold`, and
 | **Inline** | Recommended for a single sequential task; always available for a user-confirmed choice |
 | **Batch Inline** | Recommended for a bounded sequential batch; it remains serial and is never presented as parallel |
 
-Do not transition to `executing` until `execution show` reports `current: true` and the phase guard passes. A revised plan must repeat `tf execution recommend` and use `tf execution revise --confirm`; it creates a new revision and invalidates receipts from the prior revision.
+Do not transition to `executing` until `execution show` reports `current: true` and the phase guard passes. A revised plan must repeat `tf execution recommend` and use `tf execution revise --confirm`; it creates a new revision. Receipts carrying a `wave_fingerprint` stay valid while their wave definition is unchanged (v0.49.0 §83.3.2); legacy receipts without one still fall back to the plan-hash judgement and are invalidated by a revision.
 
 ## Batch Inline Execution
 
@@ -123,7 +125,11 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 1. Read the current plan with `tf execution show <change-dir> --json`; only waves shown with `current: true` and `eligible: true` may start. A `retryable: true` wave may only be repaired and re-reviewed; do not dispatch its dependents until its replacement receipt is `pass`. The CLI encodes dependencies in `--wave <id>:<strategy>:<tasks>[:<depends-on,...>]` and rejects a review receipt for a wave whose prerequisites lack current `pass` receipts.
 2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch. If it does not, disclose the unavailable capability and execute the same wave one task at a time without changing its stored strategy.
 3. A `serial` wave dispatches one task at a time in listed order.
-4. After every wave, notify workflow-start via SendMessage that the wave is complete and needs review. Include:
+4. After every wave, write back the tasks.md checkboxes for that wave, then notify workflow-start via SendMessage that the wave is complete and needs review.
+
+   **tasks.md 勾选回写（v0.49.0 §83.3.4）**：按 `wave.tasks` 匹配 tasks.md 对应行，把 `- [ ]` 改为 `- [x]`（只改勾选标记，不动任务文本）。这是执行进度的权威登记——`tasks-complete` guard 在 closing 时要求零未勾选项，留到收尾轮必然遗忘。若该 change 的 tasks.md 不使用 checkbox 形态（如以 `### Task N.M` 标题组织），零 `- [x]` 会使该 guard 无条件 FAIL：此时与 workflow-start 确认改用 checkbox 形态或走显式豁免，不要静默跳过。A1 修复后勾选不再使 plan 过期（§83.3.1），因此不会阻塞本 wave 的 receipt 登记（receipt 由 workflow-start 写入）。
+
+   Notify with:
    - Wave ID
    - Worktree path
    - Branch

package/skills/ce-compound/references/promotion-rules.md

@@ -10,7 +10,7 @@ tf solutions promote <change-dir>
 
 ## 晋升来源
 
-检查 `specs/<cap>/learnings.md` 中的经验。
+检查 change 根目录 `learnings.md` 中的经验（v0.49.0 §83.3.5 统一路径：代码与 guard 均只认 change 根，`specs/<cap>/` 下从未落地）。
 
 ## 晋升条件
 

package/skills/ce-compound/references/schema.yaml

@@ -1,5 +1,14 @@
 # Documentation schema for learnings written by ce-compound
-# Treat this as the canonical frontmatter contract for docs/solutions/.
+# Treat this as the canonical frontmatter contract for docs/solutions/ entries
+# written by ce-compound.
+#
+# v0.49.0 §83.3.5（来源：workflow-feedback 20260909）：docs/solutions/ 有两条产出通道，
+# frontmatter 契约不同 ——
+#   ① ce-compound 手工条目：使用本文件的 schema（module / problem_type / component / ...）
+#   ② tf solutions promote 自动晋升条目：phase / domain / type / severity / date / source
+#      （见 scripts/lib/solutions-promote.mjs，字段源自 change 根 learnings.md）
+# 共同消费面 = docs/solutions/INDEX.md（tf solutions inject 只读该文件，不读条目 frontmatter）。
+# 下方 schema 仅适用于通道 ①。
 #
 # The schema has two tracks based on problem_type:
 #   Bug track  — problem_type is a defect or failure (build_error, test_failure, etc.)

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

@@ -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 实施结果（团队协作：落地结果是团队最需要看的内容）：

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

@@ -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 完成后，继续下一步路由
@@ -237,7 +238,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 完成时回写（主代理只检查不代写）。主代理（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）
 

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)
-
-## 根因/模式
-（待补充）
-
-## 预防措施/应用方式
-（待补充）