@xulthekl/team-flow 0.39.1 → 0.40.1

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.39.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.40.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.39.1",
+      "version": "0.40.1",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.1",
+  "version": "0.40.1",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.1",
+  "version": "0.40.1",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.39.1"
+    "version": "0.40.1"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
-  "version": "0.39.1",
+  "version": "0.40.1",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.39.1"
+    "version": "0.40.1"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.39.1",
+      "version": "0.40.1",
       "source": ".",
       "author": {
         "name": "LT",

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.39.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.40.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.39.1**。
+当前发布版本：**v0.40.1**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.39.1`
+> 当前版本：`v0.40.1`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.39.1`
+- Current: `v0.40.1`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/solutions/INDEX.md

@@ -2,6 +2,7 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
+| 2026-08-07 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-07-no-summary.md |
 | 2026-08-06 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-06-no-summary.md |
 | 2026-08-05 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-05-no-summary.md |
 | 2026-08-04 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-04-no-summary.md |

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

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

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 24 skills, one install.",
-  "version": "0.39.1",
+  "version": "0.40.1",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.39.1: auto-sync CLI version with plugin version
+# v0.40.1: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.39.1"
+PLUGIN_VERSION="0.40.1"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.39.1.
+Current version: v0.40.1.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.39.1",
+  "version": "0.40.1",
   "description": "Unified plugin (24 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.39.1",
+  "version": "0.40.1",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/ensure-branch.mjs

@@ -24,7 +24,8 @@
 // names) and are passed as array elements, never interpolated into a shell string;
 // branch names are additionally sanitized to git-legal characters before use.
 import { execFileSync } from 'node:child_process';
-import { resolve, basename, dirname, join } from 'node:path';
+import { resolve, basename, join } from 'node:path';
+import { detectWorkspaceRoot } from './lib/git-utils.mjs';
 import { readdirSync, existsSync, appendFileSync, readFileSync } from 'node:fs';
 
 const rawChangeDir = process.argv[2];
@@ -59,13 +60,6 @@ function sanitizeBranchName(raw) {
   return cleaned || 'change';
 }
 
-// 若 change-dir 形如 <root>/changes/<name>，返回 <root>；否则返回 null。
-function detectWorkspaceRoot(absChangeDir) {
-  const parent = dirname(absChangeDir);          // <root>/changes
-  if (basename(parent) !== 'changes') return null;
-  return dirname(parent);                        // <root>
-}
-
 // 枚举 root 下含 .git 的直接子目录（= 代码仓库），按目录名排序保证确定性。
 // .git 可能是目录（普通仓库）或文件（worktree/submodule 链接），existsSync 均覆盖。
 function listCodeRepos(root) {

package/scripts/lib/arch-merge.mjs

@@ -18,13 +18,14 @@
 import {
   readFileSync, writeFileSync as fsWriteFileSync, existsSync, mkdirSync, readdirSync, rmdirSync, cpSync,
 } from 'node:fs';
-import { join, basename, dirname, resolve, sep } from 'node:path';
-import { execSync } from 'node:child_process';
+import { join, basename, dirname, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 import {
   parseTableAfter, extractEndpoints, extractAggregates,
   extractTablesFromSql, extractTablesFromDatabaseMd, readFrontmatter,
 } from './arch-parse.mjs';
+import { detectWorkspaceRoot, getGitRoot } from './git-utils.mjs';
 
 const MARKER_BEGIN = '<!-- arch:current-state:begin -->';
 const MARKER_END = '<!-- arch:current-state:end -->';
@@ -417,9 +418,9 @@ function gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun)
   try {
     // 白名单：只 add 本次 touch 的文件（防卷走他人未提交工作）
     for (const f of touchedFiles) {
-      execSync(`git add "${f}"`, { stdio: 'pipe' });
+      execFileSync('git', ['add', f], { cwd: projectRoot, stdio: 'pipe' });
     }
-    execSync(`git commit -m "${commitMsg}"`, { stdio: 'pipe' });
+    execFileSync('git', ['commit', '-m', commitMsg], { cwd: projectRoot, stdio: 'pipe' });
     return { committed: true, message: commitMsg };
   } catch (e) {
     return { committed: false, error: e.message };
@@ -427,9 +428,11 @@ function gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun)
 }
 
 /** 检测 docs/architecture/ 下非本次 touch 的脏文件（团队协作安全底线）。 */
-function detectUntouchedDirtyFiles(globalArchDir, touchedFiles) {
+function detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles) {
   try {
-    const status = execSync(`git status --porcelain -- ${globalArchDir}`, { stdio: 'pipe' }).toString();
+    const status = execFileSync('git', ['status', '--porcelain', '--', globalArchDir], {
+      cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
     const dirty = status.split('\n').filter(Boolean)
       .map(line => line.replace(/^\S+\s+/, '').trim())
       .filter(p => p && !touchedFiles.includes(resolve(p)) && !touchedFiles.includes(p));
@@ -461,9 +464,7 @@ export function run(args = {}) {
 
   let projectRoot = args.projectRoot;
   if (!projectRoot) {
-    const abs = resolve(changeDir);
-    const changesIdx = abs.lastIndexOf(sep + 'changes' + sep);
-    projectRoot = changesIdx > 0 ? abs.slice(0, changesIdx) : process.cwd();
+    projectRoot = detectWorkspaceRoot(changeDir) || getGitRoot(changeDir);
   }
 
   const changeName = basename(changeDir.replace(/\/$/, ''));
@@ -530,7 +531,7 @@ export function run(args = {}) {
       join(globalArchDir, 'INDEX.md'),
       ...(archiveResult.files || []),  // v0.36.3：changelog/ 复制文件入白名单
     ].filter(p => existsSync(p));
-    const dirty = detectUntouchedDirtyFiles(globalArchDir, touchedFiles);
+    const dirty = detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles);
     if (dirty.length > 0) {
       console.warn(`  [WARN] docs/architecture/ 存在非本次 touch 的脏文件（${dirty.length} 个）：${dirty.slice(0, 5).join(', ')} — 白名单 git add 不卷走它们，但请确认是否他人未提交工作`);
     }

package/scripts/lib/cmd-deisolate.mjs

@@ -18,6 +18,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 export async function run(args) {
   const { positionals, values } = parseArgs({
@@ -70,11 +71,6 @@ export async function run(args) {
   }
 }
 
-function detectWorkspaceRoot(absChangeDir) {
-  const parent = dirname(absChangeDir);
-  if (basename(parent) !== 'changes') return null;
-  return dirname(parent);
-}
 
 // Case A: <root>/.worktrees/<change>/<repo>/
 function detectCaseA(root, changeName) {

package/scripts/lib/cmd-execution.mjs

@@ -28,6 +28,7 @@ export async function run(args) {
       'tests-failed': { type: 'string' },
       json: { type: 'boolean', default: false },
       help: { type: 'boolean', default: false },
+      repo: { type: 'string' },
     },
     allowPositionals: true,
   });
@@ -144,7 +145,7 @@ function recordAndPrintReview(changeDir, values) {
     head: values.head,
     report: values.report,
     tests: parseTestsStats(values),
-  });
+  }, values.repo);
   print(values.json, { ok: true, wave: values.wave[0], receipt }, `Review for ${values.wave[0]} recorded: ${receipt.status}.`);
 }
 
@@ -237,6 +238,6 @@ function printHelp() {
   tf execution plan <dir> --mode <mode> --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
   tf execution show <dir> [--json]
   tf execution revise <dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
-  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--tests-total N --tests-passed N --tests-failed N]
+  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--repo <path>] [--tests-total N --tests-passed N --tests-failed N]
   tf execution refresh-hash <dir> [--json]   # refresh artifacts/contract hash without bumping revision`);
 }

package/scripts/lib/cmd-prototype.mjs

@@ -20,6 +20,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, rmSync, appendFileSync, readFileSync } from 'node:fs';
 import { join, resolve, basename } from 'node:path';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 const PROTECTED = ['main', 'master'];
 
@@ -39,12 +40,20 @@ function normalizeBranchName(raw) {
 }
 
 /** 定位 workspace root（cwd 在主仓库内）与原型仓库路径。 */
-function resolveLayout() {
+function resolveLayout(projectRootArg) {
   let workspaceRoot;
-  try {
-    workspaceRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
-  } catch {
-    throw new Error('无法定位 workspace root：cwd 不在 git 仓库内？');
+  if (projectRootArg) {
+    workspaceRoot = resolve(projectRootArg);
+  } else {
+    // 优先从 changes/ 布局推断（worktree 中 cwd 可能不是主仓库）
+    workspaceRoot = detectWorkspaceRoot(process.cwd());
+    if (!workspaceRoot) {
+      try {
+        workspaceRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+      } catch {
+        throw new Error('无法定位 workspace root：cwd 不在 git 仓库内？请使用 --project-root 指定');
+      }
+    }
   }
   const protoRepo = join(workspaceRoot, 'prototype');
   if (!existsSync(join(protoRepo, '.git'))) {
@@ -84,8 +93,8 @@ function localBranchExists(protoRepo, branch) {
 }
 
 /** 子命令 branch：创建/复用原型版本 worktree。 */
-function cmdBranch(branchName) {
-  const { workspaceRoot, protoRepo } = resolveLayout();
+function cmdBranch(branchName, projectRootArg) {
+  const { workspaceRoot, protoRepo } = resolveLayout(projectRootArg);
   const wtPath = join(workspaceRoot, '.worktrees', branchName, basename(protoRepo));
 
   // 幂等：worktree 已存在 → 复用
@@ -118,8 +127,8 @@ function cmdBranch(branchName) {
 }
 
 /** 子命令 deisolate：版本收尾 merge 回主干 + 清理 worktree。 */
-function cmdDeisolate(branchName, opts) {
-  const { workspaceRoot, protoRepo } = resolveLayout();
+function cmdDeisolate(branchName, opts, projectRootArg) {
+  const { workspaceRoot, protoRepo } = resolveLayout(projectRootArg);
   const wtPath = join(workspaceRoot, '.worktrees', branchName, basename(protoRepo));
   const result = { branch: branchName, worktreePath: wtPath };
 
@@ -181,8 +190,9 @@ function usage() {
   console.log(`tf prototype — 原型仓库版本 worktree 隔离（v0.37.0 §68.4）
 
 用法：
-  tf prototype branch <prd-vN>                 # 创建/复用原型版本 worktree（隔离 + 团队拉取）
-  tf prototype deisolate <prd-vN> [--merge] [--clean]
+  tf prototype branch <prd-vN> [--project-root <path>]
+                                               # 创建/复用原型版本 worktree（隔离 + 团队拉取）
+  tf prototype deisolate <prd-vN> [--merge] [--clean] [--project-root <path>]
                                                # 版本收尾：merge 回主干 + 清理 worktree
 
 示例：
@@ -210,13 +220,20 @@ export async function run(args = []) {
   try { branchName = normalizeBranchName(rawVersion); }
   catch (e) { console.error(e.message); process.exit(2); }
 
+  // Extract --project-root from remaining args
+  let projectRootArg;
+  const projectRootIdx = rest.indexOf('--project-root');
+  if (projectRootIdx !== -1 && rest[projectRootIdx + 1]) {
+    projectRootArg = rest[projectRootIdx + 1];
+  }
+
   try {
     if (sub === 'branch') {
-      return cmdBranch(branchName);
+      return cmdBranch(branchName, projectRootArg);
     }
     if (sub === 'deisolate') {
       const opts = { merge: rest.includes('--merge'), clean: rest.includes('--clean') };
-      return cmdDeisolate(branchName, opts);
+      return cmdDeisolate(branchName, opts, projectRootArg);
     }
     console.error(`未知子命令：${sub}（可用：branch / deisolate）`);
     process.exit(2);

package/scripts/lib/cmd-publish.mjs

@@ -19,16 +19,18 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, rmdirSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 const LOCK_PATH = '.publish.lock';
 
 /** 解析 CLI 参数。 */
 function parseArgv(argv) {
-  const parsed = { targets: [], push: false, dryRun: false, changeDir: null };
+  const parsed = { targets: [], push: false, dryRun: false, changeDir: null, projectRoot: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--push') parsed.push = true;
     else if (a === '--dry-run') parsed.dryRun = true;
+    else if (a === '--project-root') { parsed.projectRoot = argv[++i]; }
     else if (a === '--prd') parsed.targets.push('prd');
     else if (a === '--arch') parsed.targets.push('arch');
     else if (a === '--changes') {
@@ -179,17 +181,27 @@ export async function run(args = []) {
   if (parsed.help) {
     console.log(`tf publish — 阶段产物白名单提交 + 可选推送（v0.37.0 §68.3）
 
-用法：tf publish <target> [--push] [--dry-run]
+用法：tf publish <target> [--push] [--dry-run] [--project-root <path>]
   --prd         提交 PRD + orchestrator.yaml + registry.yaml + 主仓库 prototype/
   --arch        提交 docs/architecture/（迭代快照）
   --changes     提交整个 changes/（或 --changes <change-dir> 指定单个 change）
   --all         提交全部上述
   --push        同时推送到远程当前分支（默认只提交不推送）
-  --dry-run     只打印将执行的 git 动作，不落盘不 commit`);
+  --dry-run     只打印将执行的 git 动作，不落盘不 commit
+  --project-root <path>
+                显式指定主仓库根目录（多仓库 worktree 场景下自动检测失败时使用）`);
     return;
   }
 
-  const projectRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+  let projectRoot;
+  if (parsed.projectRoot) {
+    projectRoot = resolve(parsed.projectRoot);
+  } else {
+    projectRoot = detectWorkspaceRoot(process.cwd());
+    if (!projectRoot) {
+      projectRoot = git(process.cwd(), 'rev-parse', '--show-toplevel');
+    }
+  }
   const whitelist = collectWhitelist(projectRoot, parsed.targets, parsed.changeDir);
 
   if (whitelist.length === 0) {

package/scripts/lib/execution-plan.mjs

@@ -5,6 +5,7 @@ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { computeArtifactsHash, computeContractHash } from './hash.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { readState } from './state-loader.mjs';
+import { detectWorkspaceRoot, findSubRepo } from './git-utils.mjs';
 
 export const EXECUTION_MODES = ['inline', 'batch-inline', 'sdd'];
 
@@ -130,7 +131,7 @@ export function validatePlan(changeDir, plan) {
   return { valid: failures.length === 0, failures, plan };
 }
 
-export function recordReview(changeDir, waveId, receipt) {
+export function recordReview(changeDir, waveId, receipt, repoPath) {
   const plan = readPlan(changeDir);
   const validation = validatePlan(changeDir, plan);
   if (!validation.valid) throw new Error(`Cannot record a review for an invalid execution plan: ${validation.failures.join('; ')}`);
@@ -145,7 +146,7 @@ export function recordReview(changeDir, waveId, receipt) {
   }
   for (const field of ['base', 'head']) requireText(receipt?.[field], `receipt.${field}`);
   const report = validateReviewReportEvidence(changeDir, receipt?.report);
-  const { base, head } = validateReviewRange(changeDir, receipt.base, receipt.head);
+  const { base, head, subRepoPath } = validateReviewRange(changeDir, receipt.base, receipt.head, repoPath);
   // v0.13 §51.2：测试统计为可选证据字段（提供时必须为非负整数）。
   // 硬门禁在入口（test-matrix-ready）与 closing（tests-passing），此处只沉淀证据，
   // 避免单 wave 零测试造成 BUG-A 式过严死锁（DDL/脚手架类 wave 可能合理无测试）。
@@ -166,6 +167,9 @@ export function recordReview(changeDir, waveId, receipt) {
     head,
     report,
     ...(tests ? { tests } : {}),
+    // Persist repo path when SHA was resolved in a sub-repository, so
+    // readCurrentReview can re-validate without re-scanning.
+    ...(subRepoPath ? { repo: relative(changeDir, subRepoPath) } : {}),
     plan_hash: plan.hash,
     plan_revision: plan.revision,
     recorded_at: new Date().toISOString(),
@@ -187,7 +191,10 @@ export function readCurrentReview(changeDir, waveId, plan = readPlan(changeDir))
   try {
     const receipt = JSON.parse(readFileSync(filePath, 'utf8'));
     if (receipt?.plan_hash !== plan.hash || receipt?.plan_revision !== plan.revision) return null;
-    const range = validateReviewRange(changeDir, receipt?.base, receipt?.head);
+    // When the receipt records a repo path (sub-repo scenario), use it for
+    // SHA re-validation.  Otherwise fall back to the default main-repo path.
+    const repoPath = receipt?.repo ? resolve(changeDir, receipt.repo) : undefined;
+    const range = validateReviewRange(changeDir, receipt?.base, receipt?.head, repoPath);
     if (receipt.base !== range.base || receipt.head !== range.head) return null;
     // A passing receipt is current evidence only while its referenced report
     // remains safe and readable. Recheck it here because reports can be
@@ -276,10 +283,74 @@ function getPhysicalReviewsDirectory(changeDir) {
   return { changeRoot, reviewsDir: directory };
 }
 
-function validateReviewRange(changeDir, base, head) {
-  const gitRoot = getGitRoot(changeDir);
-  const resolvedBase = resolveGitCommit(gitRoot, base, 'base');
-  const resolvedHead = resolveGitCommit(gitRoot, head, 'head');
+function validateReviewRange(changeDir, base, head, repoPath) {
+  const gitRoot = resolveGitRoot(changeDir, repoPath);
+
+  let resolvedBase, resolvedHead, subRepoPath;
+  try {
+    resolvedBase = resolveGitCommit(gitRoot, base, 'base');
+    resolvedHead = resolveGitCommit(gitRoot, head, 'head');
+  } catch (primaryError) {
+    // Sub-repo fallback: when SHA is not in the main repo, scan workspace
+    // children for a sub-repository that contains it (e.g. bff/, ui/).
+    // Only attempt when --repo was not explicitly provided.
+    if (repoPath) throw primaryError;
+
+    const workspaceRoot = detectWorkspaceRoot(changeDir);
+    if (!workspaceRoot) throw primaryError;
+
+    const subRoot = findSubRepo(workspaceRoot, head);
+    if (!subRoot) throw primaryError;
+
+    resolvedBase = resolveGitCommit(subRoot, base, 'base');
+    resolvedHead = resolveGitCommit(subRoot, head, 'head');
+    subRepoPath = subRoot;
+  }
+
+  // Track when SHA was resolved outside the changeDir's own repo.
+  // This happens either through automatic fallback (subRepoPath set above)
+  // or through explicit --repo pointing to a different repository.
+  if (!subRepoPath && repoPath) {
+    const defaultRoot = resolveGitRoot(changeDir);
+    if (gitRoot !== defaultRoot) subRepoPath = gitRoot;
+  }
+
+  const effectiveRoot = subRepoPath || gitRoot;
+  const result = validateResolvedRange(effectiveRoot, resolvedBase, resolvedHead);
+  return { ...result, subRepoPath };
+}
+
+/**
+ * Resolve the git root for SHA verification. Honors an explicit --repo path;
+ * otherwise uses the changeDir's own git repository.
+ */
+function resolveGitRoot(changeDir, repoPath) {
+  if (repoPath) {
+    const absRepo = isAbsolute(repoPath) ? repoPath : resolve(changeDir, repoPath);
+    try {
+      return execFileSync('git', ['-C', absRepo, 'rev-parse', '--show-toplevel'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      throw new Error(`--repo path '${repoPath}' is not inside a Git work tree`);
+    }
+  }
+  try {
+    return execFileSync('git', ['-C', changeDir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    throw new Error('Review receipts require the change directory to be inside a Git work tree');
+  }
+}
+
+/**
+ * Validate a resolved SHA range: base must differ from head, and base must
+ * be an ancestor of head. Shared by both primary and sub-repo paths.
+ */
+function validateResolvedRange(gitRoot, resolvedBase, resolvedHead) {
   // v0.13 §51.1：禁止空 diff review（base === head）。
   // C1-domain-policy 现场曾出现 6 个 receipt 全部 base==head==初始 commit，
   // 即 review 对空 diff 进行。本校验同时强制"每 wave 落 commit"的纪律。
@@ -299,17 +370,6 @@ function validateReviewRange(changeDir, base, head) {
   return { base: resolvedBase, head: resolvedHead };
 }
 
-function getGitRoot(changeDir) {
-  try {
-    return execFileSync('git', ['-C', changeDir, 'rev-parse', '--show-toplevel'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-  } catch {
-    throw new Error('Review receipts require the change directory to be inside a Git work tree');
-  }
-}
-
 function resolveGitCommit(gitRoot, revision, field) {
   try {
     return execFileSync('git', ['-C', gitRoot, 'rev-parse', '--verify', `${revision}^{commit}`], {