@xulthekl/team-flow 0.49.0 → 0.51.0

package/scripts/lib/git-utils.mjs

@@ -11,12 +11,16 @@
  * - ensure-branch.mjs   (workspace root detection for worktree isolation)
  * - cmd-deisolate.mjs   (workspace root detection for deisolation)
  *
+ * v0.23 §92：仓清单解析收敛到本模块——`resolveCodeRepos` 是唯一入口
+ * （config `repo_layout.repos` 权威 → 两层探测 fallback），消费方不再各自枚举目录；
+ * `parsePorcelainPaths` 是 porcelain 路径解析的唯一实现（v0.23 §93）。
+ *
  * @module git-utils
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, realpathSync } from 'node:fs';
-import { isAbsolute, join, resolve, sep } from 'node:path';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
 /**
  * Detect the workspace root from a changeDir path by looking for the
@@ -65,26 +69,180 @@ export function getGitRoot(path) {
  * @returns {string|null} Absolute path to the matching sub-repo root,
  *   or null if no sub-repo contains the revision
  */
-export function findSubRepo(workspaceRoot, revision) {
+export function findSubRepo(workspaceRoot, revision, config = null) {
+  // v0.23 §92.3.4：改为遍历统一解析结果（config 权威 + 两层探测），不再自行扫直接子目录。
+  for (const repo of resolveCodeRepos(workspaceRoot, config).repos) {
+    try {
+      execFileSync('git', ['-C', repo.absPath, 'rev-parse', '--verify', `${revision}^{commit}`], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+      });
+      // Resolve symlinks (macOS /var → /private/var) for consistency with git paths
+      return realpathSync(repo.absPath);
+    } catch {
+      // Not in this repo, continue scanning
+    }
+  }
+  return null;
+}
+
+/* ============ v0.23 §92：仓清单统一解析 ============ */
+
+/** 非代码仓库目录（team-flow 产物/基础设施），探测时排除（与 conventions-generator 口径一致） */
+export const NON_REPO_DIRS = new Set([
+  'changes', '.team-flow', 'docs', 'doc', 'node_modules', '.worktrees',
+  'requirement', 'prototype', 'specs', 'data', 'path', 'template',
+]);
+
+/**
+ * @param {string} name 目录名
+ * @param {{excludeNonRepoDirs?: boolean}} [options] 是否套用 NON_REPO_DIRS 排除表（默认 true）。
+ *   枚举「工作区」时须为 true（避免把 docs/changes 等产物目录误当代码仓）；
+ *   枚举「已隔离的 worktree 目录」时应为 false——那里的结构由 ensure-branch 按 config
+ *   权威清单创建，仓名可能恰是 NON_REPO_DIRS 中的词（data / prototype / docs / …）。
+ */
+function isExcludedDir(name, { excludeNonRepoDirs = true } = {}) {
+  if (name.startsWith('.') || name === 'node_modules') return true;
+  return excludeNonRepoDirs && NON_REPO_DIRS.has(name);
+}
+
+function hasGitEntry(dir) {
+  return existsSync(join(dir, '.git'));
+}
+
+function isDirectory(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 探测 root 下的代码仓库，支持两层布局（v0.23 §92.3.3）。
+ *
+ * 层级 1：`root/<name>`（自身含 .git）
+ * 层级 2：`root/<container>/<name>`（container 自身无 .git，但含带 .git 的子目录）
+ *   —— 覆盖 `service/<repo>`、`apps/<repo>`、`packages/<repo>` 等常见布局。
+ *
+ * 深度上限 2：现有案例均为 2 层，更深无依据且易误判（node_modules 等已排除）。
+ *
+ * @param {string} root 工作区根
+ * @param {{excludeNonRepoDirs?: boolean}} [options] 见 `isExcludedDir`；默认 true（工作区探测）。
+ *   枚举已隔离的 worktree 目录时传 false——口径须与创建方（ensure-branch 的 config 权威分支）一致。
+ * @returns {Array<{name: string, relPath: string, absPath: string, isGitRepo: boolean}>} 按 relPath 排序
+ *   探测命中的条目必然含 `.git`，故 isGitRepo 恒为 true；与 `resolveCodeRepos` 的 config 分支
+ *   区分——后者可能是无 `.git` 的 monorepo 模块，消费方须按 isGitRepo 判断能否做 git 操作。
+ */
+export function listCodeReposDeep(root, { excludeNonRepoDirs = true } = {}) {
   let entries;
   try {
-    entries = readdirSync(workspaceRoot, { withFileTypes: true });
+    entries = readdirSync(root, { withFileTypes: true });
   } catch {
-    return null;
+    return [];
   }
+
+  const found = [];
+  const push = (name, relPath, absPath) => {
+    found.push({ name, relPath, absPath, isGitRepo: true });
+  };
+
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const candidate = join(workspaceRoot, entry.name);
-    if (!existsSync(join(candidate, '.git'))) continue;
+    if (!entry.isDirectory() || isExcludedDir(entry.name, { excludeNonRepoDirs })) continue;
+    const candidate = join(root, entry.name);
+
+    if (hasGitEntry(candidate)) {
+      push(entry.name, entry.name, candidate);
+      continue;
+    }
+
+    // 层级 2：容器目录（自身非仓，但子目录可能是仓）
+    let children;
     try {
-      execFileSync('git', ['-C', candidate, 'rev-parse', '--verify', `${revision}^{commit}`], {
-        stdio: ['ignore', 'ignore', 'ignore'],
-      });
-      // Resolve symlinks (macOS /var → /private/var) for consistency with git paths
-      return realpathSync(candidate);
+      children = readdirSync(candidate, { withFileTypes: true });
     } catch {
-      // Not in this sub-repo, continue scanning
+      continue;
+    }
+    for (const child of children) {
+      if (!child.isDirectory() || isExcludedDir(child.name, { excludeNonRepoDirs })) continue;
+      const childPath = join(candidate, child.name);
+      if (hasGitEntry(childPath)) {
+        push(child.name, `${entry.name}/${child.name}`, childPath);
+      }
     }
   }
+
+  return found.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+
+/**
+ * 统一仓清单解析（v0.23 §92.3.1）：config 权威 → 探测 fallback。
+ *
+ * `repo_layout.repos` 的格式兼容（LT 2026-09-09：尽量都能兼容识别）——
+ * key 与 value 均可能是相对路径 / 绝对路径 / 人类描述（人工修正产物），逐条按序尝试：
+ *   1. key 作相对路径 → `<root>/<key>`
+ *   2. value 作绝对路径
+ *   3. value 作相对路径 → `<root>/<value>`
+ *
+ * 命中判据为「**目录存在**」——repos 条目既可能是独立 git 仓（含 .git），
+ * 也可能是 monorepo 风格的 Java 模块（仅含 pom.xml，见 multi-repo-support-design §3.1）；
+ * 是否可做 git 操作由消费方按返回项的 `isGitRepo` 自行判断。全部落空 → 计入
+ * unresolved（调用方须告警，不得静默）。
+ *
+ * 解析结果为空时回退探测，避免 config 与实况矛盾时直接失效。
+ *
+ * @param {string} workspaceRoot
+ * @param {object|null} config 已加载的 team-flow.config.json 内容
+ * @returns {{repos: Array<{name,relPath,absPath,isGitRepo}>, unresolved: Array<{key,value}>, source: 'config'|'probe'}}
+ */
+export function resolveCodeRepos(workspaceRoot, config = null) {
+  const declared = config?.repo_layout?.repos;
+  const repos = [];
+  const unresolved = [];
+
+  if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
+    for (const [key, value] of Object.entries(declared)) {
+      const hit = resolveDeclaredRepo(workspaceRoot, key, value);
+      if (hit) repos.push(hit);
+      else unresolved.push({ key, value });
+    }
+  }
+
+  if (repos.length > 0) {
+    return { repos: repos.sort((a, b) => a.relPath.localeCompare(b.relPath)), unresolved, source: 'config' };
+  }
+  return { repos: listCodeReposDeep(workspaceRoot), unresolved, source: 'probe' };
+}
+
+function resolveDeclaredRepo(workspaceRoot, key, value) {
+  const candidates = [join(workspaceRoot, key)];
+  if (typeof value === 'string' && value) {
+    candidates.push(isAbsolute(value) ? value : join(workspaceRoot, value));
+  }
+  for (const dir of candidates) {
+    if (!isDirectory(dir)) continue;
+    return {
+      name: basename(dir),
+      relPath: relative(workspaceRoot, dir) || key,
+      absPath: dir,
+      isGitRepo: hasGitEntry(dir),
+    };
+  }
   return null;
 }
+
+/**
+ * 解析 `git status --porcelain` 输出为路径数组（v0.23 §93.3.1）。
+ *
+ * 格式为 `XY <path>`——X/Y 各占一位，**未暂存修改的 X 位是空格**，因此不能用
+ * `^\S+\s+` 剥离（该正则会漏掉 ` M path`，正是 v0.51.0 前 arch-merge 误报的根因）。
+ * 以 `line.slice(3)` 按固定宽度切片，并还原引号包裹与转义空格。
+ *
+ * @param {string} output git status --porcelain 的原始输出
+ * @returns {string[]} 仓库相对路径
+ */
+export function parsePorcelainPaths(output) {
+  return String(output || '')
+    .split('\n')
+    .filter(Boolean)
+    .map(line => line.slice(3).replace(/^"|"$/g, '').replace(/\\ /g, ' '));
+}

package/scripts/lib/glaf4-delegation.mjs

@@ -31,7 +31,7 @@ import { join, isAbsolute, relative, resolve, normalize, sep } from 'node:path';
 import { readState, writeState } from './state-loader.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { detectGlaf4Delegation, detectTechStack, writeGlaf4DevConfig } from './conventions-generator.mjs';
-import { detectWorkspaceRoot, getGitRoot } from './git-utils.mjs';
+import { detectWorkspaceRoot, getGitRoot, resolveCodeRepos } from './git-utils.mjs';
 import { loadConfig } from './config-loader.mjs';
 
 // DP-4 委托模式合法枚举（对应 glaf4-dev 七模式中可委托 change 的六种）
@@ -94,7 +94,10 @@ export function detectAndWriteConfig(root, delegationMode, targetRepo) {
   if (targetRepo) {
     probeRoot = targetRepo;
   } else if (repoLayout?.repos && Object.keys(repoLayout.repos).length > 0) {
-    repos = Object.values(repoLayout.repos);
+    // v0.23 §92.3.4：复用统一解析器——`Object.values(repos)` 在 value 为人类描述时
+    // 会把描述当路径去探测（emp-auth 实况），导致聚合判定静默失效。
+    const resolved = resolveCodeRepos(projectRoot, config).repos;
+    repos = resolved.length > 0 ? resolved.map(r => r.absPath) : null;
   } else if (!detectTechStack(root).language) {
     probeRoot = projectRoot;
   }

package/scripts/lib/severity.mjs

@@ -0,0 +1,71 @@
+/**
+ * severity — 经验严重度的唯一真相源（v0.23 §91，v0.51.0）
+ *
+ * 背景：severity 是**有序等级**，但此前"序"在 4 处各自定义——solutions-promote 用集合相等
+ * 表达「≥ medium」（`severity === 'high' || severity === 'medium'`）+ 本地 SEVERITY_LADDER，
+ * solutions-index-gen 与 solutions-inject 各自重复一份 SEVERITY_ORDER——导致 critical 在
+ * **晋升 / 排序 / 升级阶梯**三处同时失效。新增等级或调整序只改本文件。
+ *
+ * 约定：
+ * - SEVERITY_ORDER 数值升序 = 严重度降序（0 最高）；比较一律走 severityRank()，禁止集合相等
+ * - 未知值排最后（与历史 `?? 3` 行为等价），不阻断存量数据
+ *
+ * @module severity
+ */
+
+/** 合法取值，按严重度降序（供 CLI 校验与提示文本使用） */
+export const SEVERITY_VALUES = Object.freeze(['critical', 'high', 'medium', 'low']);
+
+export const SEVERITY_ORDER = Object.freeze({
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+});
+
+/** 重复命中时的升级阶梯（v0.49.0 §83.3.5 落盘；v0.23 §91 补 critical 封顶） */
+export const SEVERITY_LADDER = Object.freeze({
+  low: 'medium',
+  medium: 'high',
+  high: 'critical',
+});
+
+/** 未知值排序位：排在 low 之后 */
+export const SEVERITY_UNKNOWN_RANK = SEVERITY_VALUES.length;
+
+/**
+ * 取排序位。数值越小越严重；未知值排最后。
+ * @param {string} sev
+ * @returns {number}
+ */
+export function severityRank(sev) {
+  return SEVERITY_ORDER[sev] ?? SEVERITY_UNKNOWN_RANK;
+}
+
+/**
+ * 是否为合法 severity 取值。
+ * @param {string} sev
+ * @returns {boolean}
+ */
+export function isSeverity(sev) {
+  return Object.hasOwn(SEVERITY_ORDER, sev);
+}
+
+/**
+ * sev 是否达到 min 及以上（含 min 自身）。
+ * @param {string} sev
+ * @param {string} min
+ * @returns {boolean}
+ */
+export function meetsMinSeverity(sev, min) {
+  return severityRank(sev) <= severityRank(min);
+}
+
+/**
+ * 升一档；已是最高档（critical）或未知值时原样返回。
+ * @param {string} sev
+ * @returns {string}
+ */
+export function nextSeverity(sev) {
+  return SEVERITY_LADDER[sev] ?? sev;
+}

package/scripts/lib/solutions-capture.mjs

@@ -4,6 +4,7 @@
  *
  * v0.5 复利贯穿机制脚本
  * 用法：tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>"
+ *   --severity 合法取值：critical | high | medium | low（v0.23 §91.3.4 起校验，非法值报错退出）
  *
  * 功能：
  * 1. 在对应阶段目录下创建经验文件
@@ -14,6 +15,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { SEVERITY_VALUES, isSeverity } from './severity.mjs';
 
 const PHASES = ['prd', 'plan', 'architecture', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
 const MAX_INDEX_LINES = 150;
@@ -30,14 +32,26 @@ export function run(args = {}) {
   const phase = args.phase || 'cross-phase';
   const domain = args.domain || 'general';
   const type = args.type || 'insight';
+  // v0.23 §91.3.4：仅校验「显式传入」的 severity——缺省 medium 行为不变。
+  // 此前无校验，非法值静默流入 INDEX，再在 promote/index-gen/inject 三处各自降级。
+  const severityExplicit = args.severity !== undefined && args.severity !== null;
   const severity = args.severity || 'medium';
   const summary = args.summary || '(no summary)';
   const source = args.source || '';
   const dir = args.dir || 'docs/solutions';
 
+  // 注：process.exit 后补 return——真实 CLI 下 exit 即终止；测试环境 mock exit 时
+  // 不得继续执行（否则校验失败仍会写入文件，v0.23 §91.3.4 横展）。
   if (!PHASES.includes(phase)) {
     console.error(`Invalid phase: ${phase}. Valid: ${PHASES.join(', ')}`);
     process.exit(1);
+    return;
+  }
+
+  if (severityExplicit && !isSeverity(severity)) {
+    console.error(`Invalid severity: ${severity}. Valid: ${SEVERITY_VALUES.join(', ')}`);
+    process.exit(1);
+    return;
   }
 
   // 确保目录存在

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

@@ -16,9 +16,9 @@
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { severityRank } from './severity.mjs';
 
 const PHASES = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
-const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 const MAX_INDEX_LINES = 150;
 
 function parseFrontmatter(content) {
@@ -79,7 +79,7 @@ export function run(args = {}) {
 
   // 排序：severity 降序，date 降序
   entries.sort((a, b) => {
-    const sevDiff = (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3);
+    const sevDiff = severityRank(a.severity) - severityRank(b.severity);
     if (sevDiff !== 0) return sevDiff;
     return b.date.localeCompare(a.date);
   });

package/scripts/lib/solutions-inject.mjs

@@ -15,8 +15,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 };
+import { severityRank } from './severity.mjs';
 
 export function run(args = {}) {
   const phase = args.phase || 'cross-phase';
@@ -49,7 +48,7 @@ export function run(args = {}) {
   }
 
   // 按 severity 降序排序，取 top-5
-  entries.sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3));
+  entries.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
   const top5 = entries.slice(0, 5);
 
   if (top5.length === 0) {

package/scripts/lib/solutions-promote.mjs

@@ -21,6 +21,16 @@
 import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { meetsMinSeverity, nextSeverity } from './severity.mjs';
+
+/**
+ * 剥离 YAML 行尾注释（空格 + `#` 起始）——v0.23 §91 硬化：
+ * templates/learnings.md 的取值说明写在行尾注释里，若被逐字复制进 learnings.md，
+ * 注释会随取值一起进入 frontmatter，导致 severity 被判为未知值而静默不晋升。
+ */
+function stripInlineComment(raw) {
+  return raw.replace(/\s+#.*$/, '').trim();
+}
 
 function parseFrontmatter(content) {
   // learnings.md 中每个条目以 `## 标题` 开头，frontmatter 紧跟标题行之后；
@@ -31,7 +41,7 @@ function parseFrontmatter(content) {
   for (const line of match[1].split('\n')) {
     const idx = line.indexOf(':');
     if (idx > 0) {
-      fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+      fm[line.slice(0, idx).trim()] = stripInlineComment(line.slice(idx + 1));
     }
   }
   return fm;
@@ -63,8 +73,6 @@ function renderEntryBody(learning) {
   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 计数。
@@ -77,12 +85,12 @@ function confirmExistingEntry(solutionsDir, indexContent, domain, type) {
     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} |`);
+    const upgraded = nextSeverity(currentSeverity);
+    if (upgraded !== currentSeverity) {
+      lines[i] = lines[i].replace(`| ${currentSeverity} |`, `| ${upgraded} |`);
     }
     markEntryConfirmed(join(solutionsDir, cols[7]));
-    return { indexContent: lines.join('\n'), from: currentSeverity, to: nextSeverity, file: cols[7] };
+    return { indexContent: lines.join('\n'), from: currentSeverity, to: upgraded, file: cols[7] };
   }
   return null;
 }
@@ -139,7 +147,7 @@ export function run(args = {}) {
     const domain = learning.fm?.domain || 'general';
 
     // 晋升条件：severity ≥ medium 且 type = pitfall/pattern
-    const sevOk = severity === 'high' || severity === 'medium';
+    const sevOk = meetsMinSeverity(severity, 'medium');
     const typeOk = type === 'pitfall' || type === 'pattern';
     if (!sevOk || !typeOk) {
       skipped.push({

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/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

@@ -142,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

@@ -25,14 +25,21 @@ tf solutions promote <change-dir>
 
 | Severity | 含义 | 晋升行为 |
 |----------|------|----------|
-| high | 阻塞性问题或关键模式 | 必须晋升 |
+| critical | 安全 / 数据 / 合规级高危经验（凭证熵源、越权、数据损坏等） | 满足 type 条件时必然晋升；INDEX 重建后置顶 |
+| high | 阻塞性问题或关键模式 | 满足 type 条件时必然晋升 |
 | medium | 有显著影响的问题或可复用模式 | 满足 type 条件时晋升 |
 | low | 轻微问题或局部洞察 | 不晋升，保留在 change 级别 |
 
+> **晋升是 severity × type 的合取判定**（`severity ≥ medium` **且** `type ∈ {pitfall, pattern}`）——
+> 任一维度不满足即 skipped，critical 也不例外（如 `critical` + `insight` 不晋升）。
+> 「置顶」需 `tf solutions index-gen` 重建 INDEX 后生效：promote 只 append 或原地改 severity，不重排。
+> 取值域与「序」由 `scripts/lib/severity.mjs` 唯一定义（v0.23 §91）；新增等级只改该文件，不在消费点各自实现。
+> 取值**区分大小写**，须全小写（`Critical` 会被判为未知值：排最后且不晋升）。
+
 ### 已确认模式
 
 当晋升的经验与全局 INDEX 中已有条目的 domain + type 匹配时：
 1. 不创建新文件
 2. 在已有条目中标记"已确认模式"
-3. severity 升级（low → medium, medium → high）
+3. severity 升级（low → medium → high → critical）
 4. 更新 INDEX.md 中对应行的 severity 字段

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

@@ -32,7 +32,7 @@ docs/solutions/
 phase: prd          # 阶段标签：prd | plan | prototype | spec | build | review | cross-phase
 domain: auth        # 领域标签（与 PRD/change 的领域对应）
 type: pitfall       # pitfall | pattern | decision | insight
-severity: high      # high | medium | low
+severity: high      # critical | high | medium | low（序定义于 scripts/lib/severity.mjs）
 date: 2026-07-15
 source: change-id   # 来源 change（晋升时保留）
 ---