@xulthekl/team-flow 0.48.0 → 0.50.0

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/state-loader.mjs

@@ -74,6 +74,9 @@ const BUILTIN_DEFAULTS = {
   test_matrix_skip_reason: null,
   // Test evidence (v0.13 §50：tf test record 落盘的 runner 输出证据路径)
   test_evidence_path: null,
+  // Tasks gate (v0.22 §85：hotfix/tweak 跳过 spec-writer 时显式跳过 tasks.md)
+  tasks_skipped: null,
+  tasks_skip_reason: null,
   // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
   // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
@@ -196,6 +199,10 @@ export function writeState(changeDir, state) {
   lines.push('');
   lines.push('# === Test evidence (v0.13 §50) ===');
   lines.push(`test_evidence_path: ${state.test_evidence_path ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Tasks gate (v0.22 §85) ===');
+  lines.push(`tasks_skipped: ${state.tasks_skipped ?? 'null'}`);
+  lines.push(`tasks_skip_reason: ${state.tasks_skip_reason ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }

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/scripts/lint/rules/behavior-consistency.mjs

@@ -25,7 +25,9 @@ export default {
 
     // Check 2: "route to" consistency with workflow-start
     if (skillName !== 'workflow-start') {
-      const routeRefs = [...content.matchAll(/[Rr]oute to [`""]?([a-z-]+)[`""]?/g)];
+      // v0.22 §90：加 `(?![a-z\/-])` 排除路径式目标——原正则把 "route to `references/xxx.md`"
+      // 捕获为 skill 名 "references"，产生 error 级误报（ce-plan SKILL.md:64）。
+      const routeRefs = [...content.matchAll(/[Rr]oute to [`""]?([a-z-]+)[`""]?(?![a-z\/-])/g)];
       for (const [, target] of routeRefs) {
         // This skill says "route to X" — workflow-start should have a corresponding rule
         // We flag this for manual verification (can't easily cross-check without loading workflow-start)

package/scripts/team-flow.mjs

@@ -67,6 +67,8 @@ Commands:
   arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>]
                         Stamp project-level arch_baseline into .team-flow/arch-state.json (v0.35.0 §59.4)
   arch show             Show current project architecture baseline state
+  arch precheck <change-dir> [--json]
+                        Emit deterministic architecture-gate evidence (v0.22 §88; evidence only, exit 0)
   arch-merge <change-dir> [--project-root <path>] [--dry-run]
                         Merge architecture delta into global docs/architecture/
   test-merge <change-dir> [--project-root <path>] [--dry-run]
@@ -81,6 +83,9 @@ Commands:
                         Detect project layout (single/monorepo/multi-repo) + code repos, write repo_layout config (v1.0 §3)
   test record <dir> --from <runner-output> [--runner auto|maven-surefire|jest|pytest]
                         Record programmatic test evidence (v0.13 §50; feeds tests-passing gate)
+                        jest requires --json output (e.g. npx jest --json --outputFile=<path>);
+                        maven-surefire: console summary or surefire XML dir/file;
+                        pytest: terminal summary or junit XML (--junitxml)
   config [options]      Display or modify configuration
   config --resolve-model <profile>  Resolve a configured model profile without switching models
   state <sub> <dir>     Manage .team-flow.yaml state (init|check|transition|get|rebuild)
@@ -109,7 +114,9 @@ Commands:
   execution revise <change-dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...> [--acknowledge-recommendation]
                         Upgrade inline/batch to SDD, or replan existing SDD waves, as a new revision
   execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail
-                        Record one review receipt for a planned wave
+                        Record one review receipt for a planned wave.
+                        --report must resolve inside <change-dir>/.superpowers/sdd/reviews/
+                        (the change review overlay; other paths are rejected)
   deisolate <change-dir> [--merge] [--force] [--clean] [--json]
                         Show worktree status / merge branch back / clean worktree
   runtime check-update  Run a portable update check for canonical skills

package/skills/architecture-design/SKILL.md

@@ -67,7 +67,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
-- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源
+- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源；**Fast Path 下不读**（见 `### Fast Path`）
 - 全局 `docs/architecture/`（As-Is 实际态基线，已落地部分）
 - 现有 `specs/`（若有）
 
@@ -81,6 +81,20 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 4. **API 变更**：是否涉及 API 新增/变更（端点、方法签名、请求响应 schema）
 5. **DB schema 变更**：是否涉及数据库表结构、字段、索引变更
 
+### Fast Path：precheck 证据驱动（v0.22 §88.3.2）
+
+> **术语区分**：本节的 Fast Path 专指**架构判断门的快路径**，与 workflow-start 的 Fast-Path Routing（hotfix/tweak 路由）无关。
+> **优先级**：本节条件优先于下文「执行流程」与「上下文加载协议」——Fast Path 命中时，那两节的架构文件读取要求一律不适用。
+
+**先跑证据工具**：`tf arch precheck <change-dir> --json` —— 输出确定性证据（架构关键词的**变更语境**命中 / 否定命中 / 仅提及；改动文件按表现层/后端/配置/脚本/测试分类）。**正常调用退出码恒 0（缺参数属用法错误 exit 2），它是证据不是判断**。
+
+| precheck 输出 | 路径 | 行为 |
+|---|---|---|
+| `signal: none`（无正向架构关键词 ∧ 无后端文件 ∧ 无 `.sql` ∧ 有表现层文件） | **Fast Path** | 只读 `change-brief.md` + precheck 输出；本路径**不读 `docs/architecture/` 下任何文件（含 `INDEX.md`）**；执行五项检查后返回 `skipped`，reason 引用 precheck 证据 |
+| `signal: weak` / `strong` | 完整路径 | 现状（读快照 + 全局基线 + 完整五项检查） |
+
+**红线**：Fast Path 下若发现 precheck 证据与 brief 不符（如 brief 明确提到新增聚合但 precheck 未命中），**必须回退完整路径**——判断权始终在本子代理，precheck 只用于缩小输入范围。
+
 ### 路由分流（v0.35.0 新增）
 
 当产品级架构快照存在时（已建档项目），判定结果再按"产品级决策 vs change 内实现细节"分流：
@@ -103,7 +117,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 ### 执行流程
 
 ```
-1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）
+1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）——**Fast Path 裁剪为「brief + precheck 输出」**
 2. 执行五项检查
 3. 全部为否：
    → decision: skipped
@@ -196,7 +210,7 @@ architecture-design 执行时的上下文组装：
 1. 执行 `tf solutions inject --phase architecture`（失败静默）——注入 `docs/solutions/` 中 phase=architecture 的历史架构决策经验（BC 边界取舍/聚合划分理由/事件投影设计踩坑）
 2. 读取失败 / 无条目 → 静默跳过，不阻断（advisory 级，与 S1 复利注入同语义）
 
-**始终加载**：
+**始终加载**（**Fast Path 除外**——见上文 `### Fast Path`，该路径不读 `docs/architecture/` 下任何文件）：
 1. `Read docs/architecture/INDEX.md`（~50行摘要）
 2. `Read changes/<name>/change-brief.md`（如有）
 3. `Read changes/<name>/proposal.md`（如有）

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
@@ -136,9 +142,9 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 
 每个 wave 完成、通知 workflow-start 审查前，验证测试**实际执行**的数量（设计增强方案 v0.18 §76，来源：workflow-feedback 2026-08-06——64% 测试静默跳过但报告全绿）：
 
-1. 运行测试套件后，用 `tf test record <change-dir> --from <runner-output-file>` 解析**实际执行数量**（`Tests run: N`）。
+1. 运行测试套件后，用 `tf test record <change-dir> --from <runner-output-file>` 解析**实际执行数量**。**证据文件的产出形态随 runner 而异（v0.22 §86）**：jest 必须 `--json`（如 `npx jest --json --outputFile=<path>`；控制台汇总行 `Tests: N passed` 不被解析）；maven-surefire 用控制台汇总行（`Tests run: N`）或 surefire XML 目录/文件；pytest 用 terminal summary 或 junit XML（`--junitxml=<path>`）。解析规则以 `scripts/lib/test-record.mjs` 为准（新增 runner 需先在该处注册）。
 2. 对照 test-matrix 当前 wave 覆盖的用例数（**分母排除 `test_tier=e2e`**——E2E case 由 Playwright 执行，不进入 `mvn test`/`npm test` 的 `Tests run: N`，口径与 code-reviewer Step 5b / release-archivist Step 2b 一致）：实际执行数明显低于预期（< 70%）→ **警告 + 调查**（@Nested 静默跳过、测试未被发现、编译期跳过等），未查明前不得报告 "N tests pass"。
-3. 报告引用实际执行数（`Tests run: N`），而非 BUILD SUCCESS 或编译通过数量。
+3. 报告引用实际执行数（按 runner 的计数口径），而非 BUILD SUCCESS 或编译通过数量。
 
 ### Per-Task Loop
 1. **Dispatch implementer**: Load the template with `tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.

package/skills/build-executor/references/execution-modes.md

@@ -35,7 +35,7 @@ Dispatch according to the persisted plan, review each planned wave, and run a fi
 1. Read the current plan with `tf execution show <change-dir> --json`; only waves with `current: true` and `eligible: true` may start.
 2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch.
 3. A `serial` wave dispatches one task at a time in listed order.
-4. After every wave, write a review report, then record one receipt:
+4. After every wave, write a review report **inside the change review overlay** `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: other paths are rejected; the overlay is auto-created), then record one receipt:
    ```bash
    tf execution review <change-dir> \
      --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>

package/skills/build-executor/task-reviewer-prompt.md

@@ -141,9 +141,10 @@ Subagent (general-purpose):
     ## Output Format
 
     Write your full review to [REVIEW_REPORT_FILE]. This distinct review report
-    path must point to a non-empty, persisted review report before the
-    controller records a receipt. After the verdict, provide the exact receipt
-    command for the controller:
+    path must resolve inside `<change-dir>/.superpowers/sdd/reviews/` and point
+    to a non-empty, persisted review report before the controller records a
+    receipt. After the verdict, provide the exact receipt command for the
+    controller:
 
     ```bash
     tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
@@ -184,7 +185,7 @@ Subagent (general-purpose):
 - `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N` prints the path; same file the implementer worked from)
 - `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from the plan's Global Constraints section or the spec: exact values, formats, and stated relationships between components (not process rules — those are already in this template)
 - `[IMPLEMENTER_REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed report to
-- `[REVIEW_REPORT_FILE]` — REQUIRED: a distinct, persisted, non-empty file where the reviewer writes this review; this exact path is stored in the receipt
+- `[REVIEW_REPORT_FILE]` — REQUIRED: a distinct, persisted, non-empty file under `<change-dir>/.superpowers/sdd/reviews/` (the overlay) where the reviewer writes this review; this exact path is stored in the receipt
 - `[BASE_SHA]` — commit before this task
 - `[HEAD_SHA]` — current commit
 - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review package to (`scripts/review-package BASE HEAD` prints the unique path it wrote; the package never enters the controller's context)

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/code-reviewer/SKILL.md

@@ -16,7 +16,7 @@ Two responsibilities: requesting review (dispatching a reviewer subagent) and re
 1. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
 2. Dispatch `general-purpose` subagent using template at `skills/code-reviewer/code-reviewer-prompt.md`
 3. Fill placeholders: `[DESCRIPTION]` (what was built), `[PLAN_OR_REQUIREMENTS]` (contract/spec reference), `[BASE_SHA]`, `[HEAD_SHA]`, `[WAVE_ID]`, and a distinct `[REVIEW_REPORT_FILE]`.
-4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]`, then record that exact path in the wave receipt: `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
+4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]` — **inside the change review overlay** `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: other paths are rejected by the CLI; the overlay directory is auto-created). Then record that exact path in the wave receipt: `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
 5. Act on feedback: Critical/Important findings require a `fail` receipt, focused repair, re-review, and replacement `pass` receipt before a dependent wave or closing can proceed. Note Minor for later, push back with reasoning if reviewer is wrong.
 
 ### Minimality And Scope

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

@@ -105,9 +105,10 @@ Subagent (general-purpose):
     ## Output Format
 
     Write your full verdict to [REVIEW_REPORT_FILE]. This review report path
-    must point to a non-empty, persisted review report before the controller
-    records a receipt. Include the wave ID, base SHA, head SHA, and that review
-    report path. End with the exact receipt command:
+    must resolve inside `<change-dir>/.superpowers/sdd/reviews/` and point to a
+    non-empty, persisted review report before the controller records a receipt.
+    Include the wave ID, base SHA, head SHA, and that review report path. End
+    with the exact receipt command:
 
     ```bash
     tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
@@ -169,7 +170,7 @@ Subagent (general-purpose):
 - `[BASE_SHA]` — starting commit
 - `[HEAD_SHA]` — ending commit
 - `[WAVE_ID]` — planned execution wave under review
-- `[REVIEW_REPORT_FILE]` — REQUIRED: distinct, persisted, non-empty review report path stored in the execution receipt
+- `[REVIEW_REPORT_FILE]` — REQUIRED: distinct, persisted, non-empty review report path under `<change-dir>/.superpowers/sdd/reviews/` (the overlay); stored in the execution receipt
 
 **Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
 

package/skills/contract-builder/SKILL.md

@@ -113,7 +113,13 @@ See `test-matrix.md` for the full test case matrix (附属产物, 独立 hash).
 
 ### Hotfix/Tweak Exemption
 
-hotfix/tweak workflow 不生成 test-matrix.md（guard 豁免）；full workflow 确无自动化测试需求的特例（纯文档/纯配置）同理。设置显式 skip + 理由（v0.13 §48.2 可审计豁免，**不允许静默不生成**）：
+**hotfix/tweak**：不生成 test-matrix.md 与 tasks.md（guard 豁免），设置显式 skip + 理由（v0.13 §48.2 + v0.22 §85 可审计豁免，**不允许静默不生成**）：
+```bash
+tf state set <change-dir> test_matrix_skipped true && tf state set <change-dir> test_matrix_skip_reason "<一句话说明>"
+tf state set <change-dir> tasks_skipped true && tf state set <change-dir> tasks_skip_reason "<一句话说明>"
+```
+
+**full workflow 特例**（纯文档/纯配置，确无自动化测试需求）：**只**豁免测试矩阵，**不得设置 `tasks_skipped`**——`tasks.md` 是 spec-writer 的核心产物，full 路径不允许跳过（v0.22 §85.4）；该禁令**代码层强制**：`tasks-complete` 对 full/auto 置键直接 FAIL。
 ```bash
 tf state set <change-dir> test_matrix_skipped true && tf state set <change-dir> test_matrix_skip_reason "<一句话说明>"
 ```
@@ -137,13 +143,38 @@ Refresh if: scope changed in proposal, requirements changed in specs, constraint
 
 ## Hotfix Mode
 
-Generate minimal contract: Intent Lock (one sentence), Task List (numbered), Approval Gate (DP-3). Skip Scope Fence, Build Rules, Review Gates, Test Evidence. Still requires DP-3 approval.
+**适用判据**（须同时满足；任一条不满足 → 走完整契约）：
+
+1. 改动文件 ≤2
+2. 不新增/变更：API 签名、请求响应 schema、DB schema、`filter.args` 等配置契约 key
+3. 变更性质 = 文案 / 样式 / 布局 / 提示语 / 日志措辞
+
+**轻契约骨架**（目标 ≤60 行；>60 行须在 DP-3 摘要说明理由；>100 行视为不适用轻契约、回退完整契约）：
+
+| 章节 | 内容 |
+|---|---|
+| `## Intent Lock` | 1-2 句（问题 + 范围） |
+| `## 锁定值表` | 改前/改后逐字——防实现偏差的核心，必留 |
+| `## 范围栅栏` | 改动文件 + 禁改项清单 |
+| `## Execution Batch` | 编号任务（含验证任务） |
+| `## Test Matrix` | 测试策略——**代码解析锚点，标题不可删**（除非 `test_matrix_skipped=true`） |
+| `## Approval Gate (DP-3)` | 审批对象声明 |
+
+**移出轻契约**：AC 覆盖矩阵、信息量守恒核对表、DOM 结构详述、金字塔/复杂度分析、人工核验义务（改由 closing 总结承载）；Review Gates 章节不写入契约，但 **wave 级 review receipt 仍须由 build-executor 记录**——closing 的 `execution-reviews-passed` 维度对 hotfix 同样考核（`guard.mjs:75`）。
+
+**其余代码锚点**：涉及 UI 时保留 `## UX 增量`；GLAF4 委托时保留 `## GLAF4 Delegation`。除此之外的段落代码不解析，可自由裁剪；但契约全文入 `contract_hash`，裁剪后须 `tf state rebuild`。
+
+**质量不变量（不得因轻量化削减）**：锁定值逐字、范围栅栏、测试策略、Escalation 条件。
+
+Still requires DP-3 approval.
+
+**非存量 hotfix/tweak 必须设置显式 skip（v0.13 §50 + v0.22 §85）**：hotfix/tweak 不生成矩阵与 `tasks.md`，但 closing 的 `tests-passing` / `tasks-complete` 两个门禁仍考核非存量 change——生成最小契约后立即执行上方 Hotfix/Tweak Exemption 段的四条 `tf state set`，否则 release-archivist 轻量收尾会被门禁阻断（v0.22 §85：修复前 `tasks-complete` 无豁免分支，closing 死锁）。
 
-**非存量 hotfix/tweak 必须设置显式 skip（v0.13 §50）**：hotfix/tweak 不生成矩阵，但 closing 的 tests-passing 门禁仍考核非存量 change——生成最小契约后立即执行 Hotfix/Tweak Exemption 段的两条 `tf state set`（`test_matrix_skipped=true` + 理由），否则 release-archivist 轻量收尾会被门禁阻断。
+**`tasks.md` 归属（v0.22 §85）**：hotfix/tweak 默认跳过（上条），但若该 change 确实需要任务记录，`tasks.md` 由本 skill 一并产出——归属 contract-builder（本 skill 已有 `tasks.md → Execution Batches` 的 Artifact Mapping，反向生成成本最低）；任务文本不再经 spec-writer（hotfix/tweak 已跳过它）。
 
 ## Guardrails
 
-- **状态字段禁写（v0.30.0）**：仅写本 skill 的 `dp_3_*` 决策字段；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
+- **状态字段禁写（v0.30.0；v0.22 §85 澄清写入白名单）**：仅写本 skill 的 `dp_3_*` 决策字段，以及本 skill 职责内的门禁豁免键——`test_matrix_skipped` / `test_matrix_skip_reason`（v0.13 §50）、`tasks_skipped` / `tasks_skip_reason`（v0.22 §85）；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
 
 - Do not continue to implementation if ambiguity remains
 - Do not approve the contract on the user's behalf