@xulthekl/team-flow 0.46.0 → 0.48.0

package/scripts/lib/cmd-repo-layout.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * repo-layout — 项目布局检测 CLI（multi-repo-support-design v1.0 §3）
+ *
+ * 用法：tf repo-layout detect <root> [--json]
+ * 判定项目布局（single / monorepo / multi-repo）+ 代码仓库清单，写 team-flow.config.json 的 repo_layout 段。
+ * 由 workflow-start DP-0 / orchestrator S1 项目模式确认调用；detect/review/isolate 按模式路由。
+ */
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { detectRepoLayout, writeRepoLayoutConfig } from './conventions-generator.mjs';
+
+export async function run(args) {
+  const positionals = args.filter(a => !a.startsWith('--'));
+  const json = args.includes('--json');
+  const subcommand = positionals[0];
+  const root = positionals[1];
+
+  if (subcommand !== 'detect' || !root) {
+    console.error('Usage: tf repo-layout detect <root> [--json]');
+    process.exit(2);
+  }
+
+  const rootPath = resolve(root);
+  if (!existsSync(rootPath)) {
+    console.error(`❌ 项目根不存在: ${rootPath}`);
+    process.exit(1);
+  }
+  const repoLayout = detectRepoLayout(rootPath);
+  writeRepoLayoutConfig(rootPath, repoLayout);
+
+  if (json) {
+    console.log(JSON.stringify({ ok: true, ...repoLayout }));
+  } else {
+    const repoCount = Object.keys(repoLayout.repos).length;
+    console.log(`✅ repo_layout: ${repoLayout.mode}（${repoCount} 个代码仓库）`);
+    if (repoCount > 0) {
+      console.log(`   仓库清单: ${Object.keys(repoLayout.repos).join(', ')}`);
+    }
+    console.log(`   config 已写 ${rootPath}/.team-flow/team-flow.config.json`);
+  }
+}
+
+// 直接运行
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/scripts/lib/config-loader.mjs

@@ -1,10 +1,11 @@
 // Config loader for team-flow
 // Loads team-flow.config.json and merges with built-in defaults.
-// Lookup order: (1) projectRoot, (2) git root, (3) home directory.
+// Lookup order: (1) projectRoot, (2) git root, (3) workspace root, (4) home directory.
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { detectWorkspaceRoot } from './git-utils.mjs';
 
 const DEFAULTS = {
   artifacts: {
@@ -35,6 +36,12 @@ const DEFAULTS = {
     version: null,
     delegation_mode: 'auto',
   },
+  repo_layout: {
+    // 项目布局（multi-repo-support-design v1.0 §3）
+    // 项目模式确认（DP-0 / orchestrator S1）时写入；detect/review/isolate 按模式路由
+    mode: null,
+    repos: {},
+  },
 };
 
 export const MODEL_PROFILES = Object.freeze([
@@ -106,6 +113,15 @@ function findConfigFile(startDir) {
     // Not a git repo — skip
   }
 
+  // 3.5 multi-repo-support-design v1.0（P3 评审 #2 修复）：change 目录 → 工作区根（changes/ 父目录）的 .team-flow/。
+  // 根非 git 仓库的 multi-repo 下，detect 写项目根 config 后，change 目录 loadConfig 需经此读到（findConfigFile
+  // 三级查找（changeDir→git root→home）不覆盖非 git 根的项目根 .team-flow/）。
+  const workspaceRoot = detectWorkspaceRoot(startDir);
+  if (workspaceRoot && workspaceRoot !== startDir) {
+    const wsTeamFlowDir = join(workspaceRoot, '.team-flow', 'team-flow.config.json');
+    if (existsSync(wsTeamFlowDir)) return wsTeamFlowDir;
+  }
+
   // 4. Check home directory
   const homePath = join(process.env.HOME || '', 'team-flow.config.json');
   if (existsSync(homePath)) return homePath;

package/scripts/lib/conventions-generator.mjs

@@ -59,10 +59,13 @@ export function detectGlaf4DevPlugin(pluginsFilePath = PLUGINS_INSTALLED_PATH) {
  * @returns {{ is_glaf4_java: boolean, glaf4_dev_available: boolean, glaf4_dev_version: string|null, delegation_mode: 'auto'|'manual'|'off' }}
  */
 export function detectGlaf4Delegation(root, options = {}) {
-  const techStack = detectTechStack(root);
   // is_glaf4_java = Java 技术栈命中（pom.xml/build.gradle 存在即可，v2.1 §4）
   // glaf4-dev 只处理 Java，Spring/JUnit 细分由 contract-builder 已有检测负责
-  const isGlaf4Java = techStack.language === 'java';
+  // multi-repo-support-design v1.0 §4.1：多仓库下按 repos 清单聚合判定——任一仓库 Java → 项目级 true
+  const repos = Array.isArray(options.repos) ? options.repos : null;
+  const isGlaf4Java = repos && repos.length > 0
+    ? repos.some(r => detectTechStack(r).language === 'java')
+    : detectTechStack(root).language === 'java';
   const plugin = detectGlaf4DevPlugin(options.pluginsFilePath);
   const mode = options.delegationMode || 'auto';
   return {
@@ -104,6 +107,62 @@ export function writeGlaf4DevConfig(root, glaf4DevInfo) {
   writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
 
+// ── repo_layout 检测（multi-repo-support-design v1.0 §3，2026-08-21）─────────────
+
+// 非代码仓库目录（team-flow 产物/基础设施），扫描时排除
+const NON_REPO_DIRS = new Set([
+  'changes', '.team-flow', 'docs', 'doc', 'node_modules', '.worktrees',
+  'requirement', 'prototype', 'specs', 'data', 'path', 'template',
+]);
+
+/**
+ * 识别项目布局（single / monorepo / multi-repo，v1.0 §3.1）
+ * @param {string} root 项目根目录
+ * @returns {{ mode: 'single'|'monorepo'|'multi-repo', repos: Record<string,string> }}
+ */
+export function detectRepoLayout(root) {
+  // 1. 根直接含技术栈特征（pom.xml/package.json/build.gradle）→ single 或 monorepo（Maven 聚合/多子模块）
+  if (existsSync(join(root, 'pom.xml')) || existsSync(join(root, 'package.json')) || existsSync(join(root, 'build.gradle'))) {
+    // P3 评审 #6：子模块排除 NON_REPO_DIRS（changes/docs/data 等含 package.json 会被 scanSubProjects 误计为模块 → 误判 monorepo）
+    const subModules = scanSubProjects(root).filter(m => !NON_REPO_DIRS.has(m.name));
+    const repos = {};
+    for (const m of subModules) repos[m.name] = m.path;
+    return { mode: subModules.length > 0 ? 'monorepo' : 'single', repos };
+  }
+  // 2. 根无技术栈特征 → 扫描子目录识别独立代码仓库（含 .git 或有技术栈语言）
+  const repos = {};
+  const entries = readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.') || NON_REPO_DIRS.has(entry.name)) continue;
+    const sub = join(root, entry.name);
+    const hasGit = existsSync(join(sub, '.git'));
+    const tech = detectTechStack(sub);
+    if (hasGit || tech.language) {
+      repos[entry.name] = sub;
+    }
+  }
+  const repoCount = Object.keys(repos).length;
+  return { mode: repoCount >= 2 ? 'multi-repo' : 'single', repos };
+}
+
+/**
+ * 写 repo_layout 段到 team-flow.config.json（v1.0 §3.2）
+ * @param {string} root 项目根
+ * @param {{ mode: 'single'|'monorepo'|'multi-repo', repos: Record<string,string> }} repoLayout
+ */
+export function writeRepoLayoutConfig(root, repoLayout) {
+  const teamFlowDir = join(root, '.team-flow');
+  const configPath = join(teamFlowDir, 'team-flow.config.json');
+  mkdirSync(teamFlowDir, { recursive: true });
+  let config = {};
+  if (existsSync(configPath)) {
+    try { config = JSON.parse(readFileSync(configPath, 'utf-8')); } catch { config = {}; }
+  }
+  config.repo_layout = repoLayout;
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
 // ── 常量 ─────────────────────────────────────────────────────────────────────
 
 const TEMPLATE_DIR = join(import.meta.dirname, '../../templates/conventions');

package/scripts/lib/execution-plan.mjs

@@ -271,12 +271,12 @@ function getPhysicalReviewsDirectory(changeDir) {
   let directory = changeRoot;
   for (const component of ['.superpowers', 'sdd', 'reviews']) {
     directory = join(directory, component);
-    let metadata;
-    try {
-      metadata = lstatSync(directory);
-    } catch (error) {
-      throw new Error(`Review report evidence cannot read the ${component} overlay directory: ${error.message}`);
+    // multi-repo-support v1.0 §4.2（cli-command-2 修复）：overlay 目录自动创建，修 ENOENT
+    // （首次 review 时 .superpowers/sdd/reviews/ 尚不存在，recordReview 写入前先建）
+    if (!existsSync(directory)) {
+      mkdirSync(directory, { recursive: true });
     }
+    const metadata = lstatSync(directory);
     if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
       throw new Error('Review report evidence requires physical .superpowers/sdd/reviews overlay directories');
     }
@@ -312,8 +312,11 @@ function validateReviewRange(changeDir, base, head, repoPath) {
   // 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;
+    // multi-repo-support v1.0 §4.2（cli-command-2 修复）：--repo 场景下 change 目录可能无 git
+    //（多仓库 changes/ 未版本化），defaultRoot 比较容错返回 null，不因 change 目录无 git 报错
+    let defaultRoot = null;
+    try { defaultRoot = resolveGitRoot(changeDir); } catch {}
+    if (defaultRoot && gitRoot !== defaultRoot) subRepoPath = gitRoot;
   }
 
   const effectiveRoot = subRepoPath || gitRoot;

package/scripts/lib/glaf4-delegation.mjs

@@ -3,8 +3,10 @@
  * glaf4-delegation — GLAF4 委托协议 CLI（v2.1 §6.6/§6.3/§6.7，P2 实施委托全链路）
  *
  * 用法：
- *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--json]
- *       运行时探测（v2.1 §4 接口①，C1 修复接线）：三态检测 + 写 .team-flow/team-flow.config.json 的 glaf4_dev 段。
+ *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--target-repo <模块路径>] [--json]
+ *       运行时探测（v2.1 §4 接口①，C1 修复接线 + multi-repo-support v1.0 §4.1）：
+ *       root 解析（change 目录→项目根）+ 写 .team-flow/team-flow.config.json 的 glaf4_dev 段（项目根）。
+ *       multi-repo 下按 repo_layout 清单聚合判定 is_glaf4_java；--target-repo 精确探测指定模块。
  *       contract-builder 产出 execution-contract 时（DP-4 前）显式调用此命令，recommend 才能读到 glaf4_dev。
  *   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json> [--json]
  *       DP-4 委托方案确认：mode 枚举标量入 state，write_set_boundary 落 .superpowers/glaf4/write-set.json，
@@ -28,7 +30,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 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, writeGlaf4DevConfig } from './conventions-generator.mjs';
+import { detectGlaf4Delegation, detectTechStack, writeGlaf4DevConfig } from './conventions-generator.mjs';
+import { detectWorkspaceRoot, getGitRoot } from './git-utils.mjs';
+import { loadConfig } from './config-loader.mjs';
 
 // DP-4 委托模式合法枚举（对应 glaf4-dev 七模式中可委托 change 的六种）
 export const GLAF4_DELEGATION_MODES = [
@@ -72,26 +76,42 @@ export function hashWriteSet(writeSet) {
  * @param {string} [delegationMode] 覆盖 delegation_mode（auto/manual/off）
  * @returns {object} { ok, is_glaf4_java, glaf4_dev_available, glaf4_dev_version, delegation_mode, configPath }
  */
-export function detectAndWriteConfig(root, delegationMode) {
-  const detection = detectGlaf4Delegation(root, { delegationMode });
+export function detectAndWriteConfig(root, delegationMode, targetRepo) {
+  // multi-repo-support-design v1.0 §4.1（cli-command-1 修复）：root 解析——change 目录（含 changes/）→ 项目根；否则 git 根
+  const projectRoot = resolveProjectRoot(root);
+
+  // 读 repo_layout（config 已固化时）
+  const config = loadConfig(projectRoot);
+  const repoLayout = config?.repo_layout || null;
+
+  // 探测目标构造（P3 自查补全 + P4 validator W1 放宽，2026-08-21）：
+  //   --target-repo 精确 > repo_layout 清单聚合（repos 非空即聚合，不限 multi-repo——
+  //   壳仓库含 package.json 误判 monorepo 时也应聚合，否则 cli-command-1 在真实项目失效）>
+  //   root 有技术栈（探测 root，如 detect(svcA)）>
+  //   root 无技术栈（change 文档目录/容器根）→ 探测解析后项目根（单仓库项目根有 pom.xml）
+  let repos = null;
+  let probeRoot = root;
+  if (targetRepo) {
+    probeRoot = targetRepo;
+  } else if (repoLayout?.repos && Object.keys(repoLayout.repos).length > 0) {
+    repos = Object.values(repoLayout.repos);
+  } else if (!detectTechStack(root).language) {
+    probeRoot = projectRoot;
+  }
+  const detection = detectGlaf4Delegation(probeRoot, { delegationMode, repos });
 
-  // 复评 C1 嵌套工程根盲区（2026-08-18）：git root ≠ target_root（monorepo 布局）时，
-  // loadConfig(changeDir) 只查 changeDir→git root→home，不查 target_root → 委托链静默断裂。
-  // 写 git root 冗余副本保证从任意 changeDir 都能读到探测结果。gitRoot 提前解析供 mode 优先级使用。
+  // git root（冗余副本判断 + mode 优先级）
   let gitRoot = null;
   try {
-    gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
-      cwd: root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+    gitRoot = getGitRoot(projectRoot);
   } catch {
     // 非 git 仓库，跳过
   }
 
-  // 第四轮复评 Important（2026-08-18）：delegation_mode 优先级链补全——显式 > 目标 root 已有 > git root 已有 > auto。
-  // 上轮只查目标 root，非 Java 服务无本地 config → 默认 auto → 覆盖 git root 副本的 off（用户 off 意图被静默翻转）。
+  // delegation_mode 优先级链：显式 > 目标 root 已有 > git root 已有 > auto
   let effectiveMode = delegationMode;
   if (!effectiveMode) {
-    effectiveMode = readGlaf4DelegationMode(root)
+    effectiveMode = readGlaf4DelegationMode(projectRoot)
       || (gitRoot ? readGlaf4DelegationMode(gitRoot) : null)
       || 'auto';
   }
@@ -100,16 +120,17 @@ export function detectAndWriteConfig(root, delegationMode) {
     version: detection.glaf4_dev_version,
     delegationMode: effectiveMode,
   };
-  writeGlaf4DevConfig(root, info);
+  // config 主副本写项目根（cli-command-1 修复：不再写 change 目录）
+  // multi-repo-support v1.0：OR 聚合保留已有 enabled=true——项目级 GLAF4 能力一旦声明，
+  // 不因后续非 Java 目标探测而覆盖丢失（非 Java change detect 不应禁用项目委托）
+  const existingProjEnabled = readGitRootGlaf4Enabled(projectRoot);
+  const projEnabled = info.enabled || existingProjEnabled;
+  writeGlaf4DevConfig(projectRoot, { ...info, enabled: projEnabled, delegationMode: effectiveMode });
 
   let gitRootConfig = null;
-  if (gitRoot && gitRoot !== root) {
-    // 第三轮复评 Important①（2026-08-18）：多服务混合 monorepo 下 git root 副本 last-write-wins 污染——
-    // 非 Java 服务 detect 会把 Java 服务的 enabled=true 覆盖成 false。改为 OR 聚合：
-    // 项目级能力一旦声明（任一服务 enabled=true），不因后续非 Java 服务探测而丢失。
+  if (gitRoot && gitRoot !== projectRoot) {
     const existingEnabled = readGitRootGlaf4Enabled(gitRoot);
     const aggregatedEnabled = info.enabled || existingEnabled;
-    // 第四轮复评：git root 副本 mode 保留已有值（显式传参才覆盖）——用户 off 意图不因新探测静默翻转。
     const gitRootMode = readGlaf4DelegationMode(gitRoot);
     const gitRootEffectiveMode = delegationMode || gitRootMode || effectiveMode;
     writeGlaf4DevConfig(gitRoot, { ...info, enabled: aggregatedEnabled, delegationMode: gitRootEffectiveMode });
@@ -119,11 +140,27 @@ export function detectAndWriteConfig(root, delegationMode) {
   return {
     ok: true,
     ...detection,
-    configPath: join(root, '.team-flow', 'team-flow.config.json'),
+    configPath: join(projectRoot, '.team-flow', 'team-flow.config.json'),
     gitRootConfig,
+    projectRoot,
   };
 }
 
+/**
+ * root 解析（multi-repo-support-design v1.0 §4.1）：change 目录（含 changes/）→ 项目根；否则 git 根；兜底直接用 root
+ * @param {string} root
+ * @returns {string}
+ */
+function resolveProjectRoot(root) {
+  const ws = detectWorkspaceRoot(root);
+  if (ws) return ws;
+  try {
+    return getGitRoot(root);
+  } catch {
+    return root;
+  }
+}
+
 /**
  * 读 git root 现有 config 的 glaf4_dev.enabled（第三轮复评 Important① OR 聚合用）
  * @param {string} gitRoot
@@ -394,7 +431,7 @@ export function resetDelegation(changeDir) {
 
 export async function run(args) {
   const positionals = args.filter(a => !a.startsWith('--'));
-  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--json'));
+  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--target-repo' && a !== '--delegation-mode' && a !== '--json'));
   const opt = (name) => {
     const i = args.indexOf(`--${name}`);
     return i >= 0 ? args[i + 1] : undefined;
@@ -404,7 +441,7 @@ export async function run(args) {
   const json = flags.has('--json') || args.includes('--json');
 
   const usage = `Usage:
-  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>]
+  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>] [--target-repo <模块路径>]
   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json-file>
   tf glaf4-delegation verify-write-set <change-dir> --run-dir <run-dir>
   tf glaf4-delegation verify-tasks <change-dir>
@@ -424,15 +461,16 @@ export async function run(args) {
   try {
     if (subcommand === 'detect') {
       const mode = opt('delegation-mode');
+      const targetRepo = opt('target-repo');
       // 第四轮复评 Minor-1（2026-08-18）：枚举校验——非法值（如 'foo'）等同 auto 放行会让用户配置失真
       if (mode !== undefined && !['auto', 'manual', 'off'].includes(mode)) {
         console.error(`--delegation-mode 必须为 auto/manual/off 之一（实际: ${mode}）`);
         process.exit(2);
       }
-      const result = detectAndWriteConfig(changeDir, mode);
+      const result = detectAndWriteConfig(changeDir, mode, targetRepo);
       const msg = result.glaf4_dev_available
-        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}`
-        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}`;
+        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}${result.projectRoot ? `（项目根 ${result.projectRoot}）` : ''}`
+        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}${result.projectRoot ? `（项目根 ${result.projectRoot}）` : ''}`;
       print(result.ok, result, msg);
     } else if (subcommand === 'confirm') {
       const mode = opt('mode');

package/scripts/team-flow.mjs

@@ -42,6 +42,7 @@ const COMMANDS = {
   'test-matrix-export': () => import('./lib/test-matrix-export.mjs'),
   'glaf4-evidence-export': () => import('./lib/glaf4-evidence-export.mjs'),
   'glaf4-delegation': () => import('./lib/glaf4-delegation.mjs'),
+  'repo-layout': () => import('./lib/cmd-repo-layout.mjs'),
   test:                () => import('./lib/test-record.mjs'),
 };
 
@@ -76,6 +77,8 @@ Commands:
                         Aggregate glaf4-dev run PASS evidence → surefire line (v2.1 §7; feed test record --from)
   glaf4-delegation <sub> <dir> [--mode <m> --write-set <json> | --run-dir <run> | --delegation-mode <mode>]
                         GLAF4 委托协议 (v2.1 §4/6.3/6.6/6.7): detect / confirm / verify-write-set / verify-tasks / record-partial / reset
+  repo-layout detect <root>
+                        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)
   config [options]      Display or modify configuration

package/skills/ce-brainstorm/SKILL.md

@@ -19,7 +19,7 @@ Brainstorming answers **WHAT** to build through collaborative dialogue, producin
 
 > **显式参数规约**：orchestrator 调用时必须传入 `mode: orchestrated`。ce-brainstorm 检测到该参数即跳过 Phase 3.5 并在输出中回执"原型循环已委托编排层"。未收到该参数时默认为 standalone 模式。
 >
-> **重要：`orchestrated` 模式仅跳过 Phase 3.5（原型内循环）。Phase 0（含 PRD 模板选择）、Phase 1（含 1.4/1.5/1.6）、Phase 2、Phase 3、QA-4、Phase 3.6、版本归档均正常执行，不可跳过。**
+> **重要：`orchestrated` 模式仅跳过 Phase 3.5（原型内循环）。Phase 0（含 PRD 模板选择）、Phase 1（含 1.3b/1.4/1.5/1.6）、Phase 2、Phase 3、QA-4、Phase 3.6、版本归档均正常执行，不可跳过。**
 
 ## Core Principles
 
@@ -40,12 +40,12 @@ Brainstorming answers **WHAT** to build through collaborative dialogue, producin
 | 职责 | 执行方 | 说明 |
 |------|--------|------|
 | 需求澄清、场景确认、流程确认、方案决策 | **主会话** | 需要用户交互和判断的工作 |
-| PRD 文档撰写（Phase 3） | **子代理**（推荐） | 执行性文档生成，主会话做 QA 和冻结 |
+| PRD 文档撰写（Phase 3） | **prd-writer agent**（v0.47） | 执行性文档生成（契约级 §8.4），主会话做 QA 和冻结 |
 | 流程图绘制（mermaid） | **子代理**（推荐） | 基于已确认的流程数据生成图表 |
 | 活动表批量生成 | **子代理**（推荐） | 基于已确认的 L4 子流程生成表格 |
 | 综合报告（synthesis summary） | **子代理**（可选） | 大量数据的汇总整理 |
 
-**子代理委托方式**：使用 `Agent` 工具（`context: fork` 或自定义 agent），将已确认的结构化数据作为输入，要求子代理按模板产出。主会话审查产出后决定接受或修正。
+**子代理委托方式**：使用 `Agent` 工具（`context: fork` 或自定义 agent），将已确认的结构化数据作为输入，要求子代理按模板产出。主会话审查产出后决定接受或修正。PRD 撰写（Phase 3）固定委托命名 agent **prd-writer**（预加载 ce-brainstorm，只执行 Phase 3、不提问）；其余执行性产出（流程图/活动表/综合报告）可委托通用子代理。
 
 ### Stage Breakpoints
 
@@ -155,6 +155,8 @@ For detailed routing logic, read `references/phase0-routing.md`. Summary:
 
 **1.3 Dialogue** — Follow Interaction Rules. Fire blindspot gate (if tripwire armed) and visual-probe gate (before first shape decision). Rigor probes fire as open-ended questions before Phase 2. Before exit: integration check for non-obvious consequences. **Exit when**: primary actor, outcome, scope, success criteria all known or recorded as assumptions.
 
+**1.3b 功能细节澄清（v0.47）** — Follow the brainstorm profile's「功能细节（契约级）」core dimension. Standard/Deep scope **强制契约级澄清**（UI 布局/字段/交互/异常/权限；非 UI 触发/输入输出/处理/异常/幂等并发/性能），Lightweight 简化。产出 **detail_ledger**（`requirement/vN/detail-ledger.md`，逐功能维度 → 已澄清/待澄清/NA），供 Phase 3 §8.4 撰写 + 冻结前 D6 核对。
+
 **1.4 Dialogue Log Persistence** — Automated step, no user interaction. Trigger: Phase 1.3 dialogue exits. Traverse each Q&A round extracting original text + decisions, generate dialogue summary and decision summary table. Write to `requirement/vN/dialogue-log.md` (create or append). No ledger update.
 
 **1.5 Business Scenario Analysis** — Read `references/business-scenarios.md` for methodology. Trigger: Phase 1.4 completed. Extract business scenarios from dialogue and context, produce QA-1 quality check, then **blocking question** for user confirmation. Output: `requirement/vN/business-analysis.md` (requirements + scenarios sections). Status marked 🔵 pending confirmation, ✅ confirmed on user approval. No ledger update at this stage.
@@ -191,34 +193,23 @@ Propose **2-3 approaches** (or recommend directly if one is clearly best). Use n
 - `requirement/ledger.md` — all requirement/scenario/process items and their associations
 - `requirement/vN/dialogue-log.md` — §1.2 revision record reference path
 - `requirement/vN/business-analysis.md` — data source for §2/§3/§7/§8
+- `requirement/vN/detail-ledger.md` — 功能细节澄清产出（v0.47），§8.4 逐功能详述数据源 + D6 核对基准
 
 **⛔ MANDATORY：生成PRD文档前，必须先读取 `references/brainstorm-sections.md`**
 
-**§8.4 功能模块提取规则（关键规则，必须遵守）**：
-- **详细程度**：保留原始需求文档中的关键细节，不要过度概括
-- **必须保留的内容**：
-  - 页面布局（上下分栏、标准列表等）
-  - 搜索模块（具体字段）
-  - 表格列定义（完整字段列表）
-  - 交互规则（默认选中、点击切换、筛选联动等）
-  - 按领域动态字段（如有）
-  - 动态列名说明
-  - 操作说明（已发布/草稿状态等）
-  - 级联选择逻辑（如有）
-- **⛔ 错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节
-- **⛔ 正确行为**：充分利用原始需求文档的详细内容，保持信息完整性
+**§8.4 功能模块提取规则（v0.47）**：规范唯一权威 = 模板 `templates/prd.md` §8.4「必含维度检查清单」（UI 11 维 / 非 UI 7 维双形态 + NA 机制），**本处不再重复维护维度清单**。生成 PRD 前必须读取模板检查清单，逐功能模块按适用维度详述；维度不适用标注 `NA + 理由`；**未标注 NA 且未覆盖 = 缺失**。
 
 Read `references/brainstorm-sections.md` for doc-warranted criteria. If warranted: read template from `PRD_TEMPLATE_PATH`, fill via `references/prd-mapping.md`, write to `requirement/{ITERATION_VERSION}/prd.md`. Vocabulary capture: update `CONCEPTS.md` with resolved domain terms (only if it exists).
 
-> **子代理委托建议**：Phase 3 PRD 文档撰写是执行性工作，建议委托子代理完成。主会话将已确认的结构化数据（business-analysis.md + dialogue-log.md + synthesis summary）作为输入传给子代理，子代理按模板填充后产出 PRD 草稿，主会话负责 QA-4 审查和冻结确认。
+> **子代理委托（v0.47）**：Phase 3 PRD 撰写委托 **prd-writer** agent。主会话将已确认结构化数据（business-analysis.md + dialogue-log.md + **detail_ledger** + synthesis summary + template_path）作为参数传入；prd-writer 按模板 §8.4 契约级检查清单逐功能详述，不提问、不虚构，`missing_info` 返回主会话决定是否回 Phase 1.3 补澄清。主会话负责 QA-4 审查和冻结确认。
 
 ### Phase 3.5: Prototype Inner Loop
 
-**`orchestrated` mode skips this phase.** For standalone: read `references/prototype-loop.md`. Trigger: PRD has UI functions. Steps: produce prototype → review vs PRD → fix loop (max 3) → completeness review → freeze PRD.
+**`orchestrated` mode skips this phase.** For standalone: read `references/prototype-loop.md`. Trigger: PRD 有 UI 功能则执行原型循环；**完整性评审（§3.5.5）对 standalone 全路径适用**（含非 UI / 跳过原型路径，不因无 UI 而跳过）。Steps: produce prototype → review vs PRD → fix loop (max 3) → completeness review → freeze PRD.
 
 ### QA-4: PRD Quality Check
 
-Fires after Phase 3 (or Phase 3.5 if prototype loop ran). Read `references/evidence-chain-validation.md` for QA-4 criteria. Evaluates PRD completeness and traceability against business analysis artifacts.
+Fires after Phase 3 (or Phase 3.5 if prototype loop ran). Read `references/evidence-chain-validation.md` for QA-4 criteria. Evaluates PRD completeness and traceability against business analysis artifacts. **冻结前完整性评审（6 维，含 §8.4 契约级细节 D6）的派发点已归并**：standalone 路径由 Phase 3.5（`references/prototype-loop.md` §3.5.5）派发 prd-completeness-reviewer；orchestrated 路径由 orchestrator S2 派发（见 `workflow-orchestrator/references/s2-prd-prototype-loop.md`）；**QA-4 自身不重复派发**，仅按评审结果判定是否回 Phase 1.3/Phase 3 修订。
 
 ### Phase 3.6: PRD ↔ Scenario/Process Bidirectional Validation
 
@@ -250,6 +241,7 @@ requirement/
 ├── vN/                                # Iteration version
 │   ├── prd.md                         # PRD document
 │   ├── dialogue-log.md                # Dialogue log (Phase 1.4 output)
+│   ├── detail-ledger.md               # 功能细节澄清产出（v0.47，§8.4 数据源 + D6 核对基准）
 │   └── business-analysis.md           # Business analysis (requirements + scenarios + processes)
 doc/
 └── active-registry/

package/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -267,17 +267,9 @@ as template placeholder.
   所属流程 (BP-xxx). Skip §8.3 (hardware/network) and §8.5 (non-functional)
   unless the brainstorm explicitly covered these.
 
-  **§8.4 功能模块提取规则**：
-  - **详细程度**：保留原始需求文档中的关键细节，不要过度概括
-  - **必须保留的内容**：
-    - 页面布局（上下分栏、标准列表等）
-    - 搜索模块（具体字段）
-    - 表格列定义（完整字段列表）
-    - 交互规则（默认选中、点击切换、筛选联动等）
-    - 按领域动态字段（如有）
-    - 动态列名说明
-    - 操作说明（已发布/草稿状态等）
-    - 级联选择逻辑（如有）
+  **§8.4 功能模块提取规则（v0.47）**：
+  - **规范权威**：模板 `templates/prd.md` §8.4「必含维度检查清单」是唯一权威（UI 11 维/非 UI 7 维双形态 + NA 机制），本文件不再重复维护维度清单。撰写（prd-writer）与审查（prd-completeness-reviewer D6）均以模板为基准。
+  - **详细程度**：保留原始需求文档中的关键细节，不要过度概括（页面布局/搜索字段/表格列/交互规则/动态字段/级联逻辑等——逐项见模板检查清单）
   - **错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节
   - **正确行为**：充分利用原始需求文档的详细内容，保持信息完整性
 

package/skills/ce-brainstorm/references/evidence-chain-validation.md

@@ -16,7 +16,7 @@ This reference covers three connected operations after PRD generation: QA-4 qual
 | C5 | Consistency | PRD §2 process overview table matches business-analysis.md process list? | Error |
 | C6 | Consistency | PRD §3 process descriptions match business-analysis.md process details? | Error |
 | C7 | Metadata | PRD frontmatter complete (title / project_name / iteration_version / date / prd_template)? | Warning |
-| C8 | Format | §8.4 feature extraction preserves original requirements detail (not over-summarized)? | Warning |
+| C8 | Detail | §8.4 契约级细节：逐功能模块按模板检查清单覆盖适用维度（UI 11 维/非 UI 7 维，单一权威 = 模板 §8.4）+ §7↔§8.4 交叉核对无悬空功能（v0.47 并入 D6 模型：核心维度缺失/悬空 = Critical，辅助维度缺失 = Important） | Critical |
 
 **Verdict rule:** All Error-level checks pass → PASS. Any Error fails → FAIL. Warnings are reported but do not block.
 

package/skills/ce-brainstorm/references/prototype-loop.md

@@ -9,8 +9,8 @@ PRD 文档写入后、Handoff 之前，执行原型内循环。原型是 PRD 的
 检查 PRD 草稿中是否包含 UI/画面/交互相关功能点（§4 画面原型、§7 系统功能清单中的 UI 功能）。
 
 - **包含 UI 功能点** → 使用平台阻塞问题工具询问用户："PRD 包含 UI 功能点，是否需要产出原型进行验证？"
-- **不包含 UI 功能点** → 跳过原型内循环，直接进入 Phase 4
-- **用户选择跳过** → 跳过，PRD 直接冻结
+- **不包含 UI 功能点** → 跳过原型内循环，**先走 §3.5.5 PRD 完整性评审，再冻结（§3.5.6，跳过 prototype-review.md 写入）**，进入 Phase 4
+- **用户选择跳过** → 跳过原型，**先走 §3.5.5 PRD 完整性评审**，再冻结
 
 ## 3.5.2 原型产出
 
@@ -37,19 +37,21 @@ PRD 文档写入后、Handoff 之前，执行原型内循环。原型是 PRD 的
 - **最多循环 3 次**，超过则标记为"需人工介入"，在 PRD 中记录未解决项
 - 每次修正触发复利捕获：`tf solutions capture --phase prd --domain <domain> --type pitfall --severity medium --summary "<修正原因>"`
 
-## 3.5.5 PRD 完整性评审（冻结前门禁）
+## 3.5.5 PRD 完整性评审（冻结前门禁，v0.47 全路径适用）
 
-原型审查通过后、冻结前，派发 `prd-completeness-reviewer` 子代理（独立上下文），评审 PRD「是否完整到能支撑后续 plan/spec 实施」（区别于 Phase 2.6 claim verifier——后者管"说得对不对"，本评审管"说得全不全"）。
+**所有 standalone 路径的冻结前必过门禁**：有原型（原型审查通过后）、无 UI 功能点（§3.5.1）、用户跳过原型（§3.5.1）三条路径均须派发——不因跳过原型循环而跳过完整性评审（orchestrated 路径对应 `s2-prd-prototype-loop.md` step 3.5）。
 
-- 派发：按名派发插件 agent `prd-completeness-reviewer`（定义见插件 `agents/prd-completeness-reviewer.md`），传入 PRD 路径 + CONCEPTS.md 路径。
+派发 `prd-completeness-reviewer` 子代理（独立上下文），评审 PRD「是否完整到能支撑后续 plan/spec 实施」（区别于 Phase 2.6 claim verifier——后者管"说得对不对"，本评审管"说得全不全"）。
+
+- 派发：按名派发插件 agent `prd-completeness-reviewer`（定义见插件 `agents/prd-completeness-reviewer.md`），传入 `prd_path` + `concepts_path`（可选）+ `template_path`（默认 `templates/prd.md`）+ `detail_ledger_path`（如有）。
 - agent 直接写审查报告到 `requirement/{ITERATION_VERSION}/prd-completeness-review.md`。
-- 判定（柔性）：PASS / PASS_WITH_WARNINGS → 进入冻结；**FAIL（Critical>0）→ 回 Phase 1.3 补充**后重审。
-- 5 维度：用户故事完整性(Critical)/验收标准(Critical)/边界与非功能(Important)/术语一致性(Minor)/范围闭环(Important)。
+- 判定（柔性）：PASS / PASS_WITH_WARNINGS → 进入冻结；**FAIL（Critical>0）→ 回 Phase 1.3/Phase 3 补充**后重审。
+- 6 维度：用户故事完整性(Critical)/验收标准(Critical)/边界与非功能(Important)/术语一致性(Minor)/范围闭环(Important)/§8.4 契约级细节（核心维度缺失·悬空功能=Critical，辅助维度缺失=Important）。
 
 ## 3.5.6 冻结
 
 完整性评审通过后：
-1. 写入 `requirement/{ITERATION_VERSION}/prototype-review.md`（审查结论 + 版本 + 日期 + 循环次数）
+1. 写入 `requirement/{ITERATION_VERSION}/prototype-review.md`（审查结论 + 版本 + 日期 + 循环次数；**无原型路径跳过本步**，完整性评审结论已落盘 `prd-completeness-review.md`）
 2. PRD 标记为 frozen（在 PRD frontmatter 中增加 `frozen: true` + `frozen_date: YYYY-MM-DD`），并在正文标题下插入冻结声明（措辞见 `references/prd-mapping.md`「冻结声明」节）
 3. **冻结语义为 `frozen_downstream`（非升版）**：后续阶段（ce-plan、spec-writer）**不可直接回改** PRD；如 plan 或实施暴露 scope 问题，经 **S3→S2 回退在 vN 内修订**并记录「决策与变更履历」（不升版）。**仅当启动新迭代 vN+1 或用户显式绝对冻结（`frozen: absolute`）时才需升版。**
 4. 同步更新正文 §1.1 文档状态为「已冻结-下游」（与 frontmatter `frozen: true` 一致）

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

@@ -9,17 +9,19 @@
 contract-builder 产出 execution-contract 时（DP-4 前）实时探测——**显式运行 CLI 命令**（第三轮复评接线统一：探测必须写 config，纯库函数不落盘）：
 
 ```bash
-tf glaf4-delegation detect <target_root> [--delegation-mode <auto|manual|off>]
+tf glaf4-delegation detect <target_root> [--delegation-mode <auto|manual|off>] [--target-repo <模块路径>]
 ```
 
+**target_root 语义（multi-repo-support-design v1.0 §4.1，cli-command-1 修复）**：传入**项目根或 change 目录均可**——detect 自动解析：change 目录（含 `changes/`）→ 项目根，config 主副本写**项目根** `.team-flow/team-flow.config.json`（不写 change 目录）。**多仓库项目（`repo_layout: multi-repo`）推荐传 `--target-repo <模块路径>`**（如 change 涉及 `batch-fytx-msg`），或依赖自动扫描：按 `repo_layout.repos` 清单聚合判定——任一代码仓库是 Java → 项目级 `is_glaf4_java=true`。
+
 `detect` 内部调用 `conventions-generator.mjs` 的 `detectGlaf4Delegation(root)` 解析 `~/.claude/plugins/installed_plugins.json`（glaf4-dev 条目含 installPath + version），产出三态：
 
-- `is_glaf4_java`（技术栈命中：pom.xml/build.gradle + Spring Boot/JUnit5/Mockito）
+- `is_glaf4_java`（技术栈命中：pom.xml/build.gradle + Spring Boot/JUnit5/Mockito；**多仓库下按 repos 清单聚合，任一仓库 Java → true**）
 - `glaf4_dev_available`（插件可用，含 version）
 - `delegation_mode`（auto/manual/off，用户可开关）
 
-探测结果写 `team-flow.config.json` 的 `glaf4_dev: {enabled, version, delegation_mode}` 段
-（git root ≠ target_root 时写 git root 冗余副本，monorepo 下多服务 OR 聚合；未传 `--delegation-mode` 保留已有值）。
+探测结果写 `<项目根>/.team-flow/team-flow.config.json` 的 `glaf4_dev: {enabled, version, delegation_mode}` 段
+（git root ≠ target_root 时写 git root 冗余副本；未传 `--delegation-mode` 保留已有值）。
 
 **判定**：`is_glaf4_java && glaf4_dev_available && delegation_mode !== 'off'` → 产出 GLAF4 Delegation 段。
 **依赖**：`recommendExecutionModesForChange` 读 `config.glaf4_dev.enabled` 决定是否注入 glaf4-delegation——**必须**先跑 detect 写 config，否则委托链不可达。

package/skills/workflow-orchestrator/SKILL.md

@@ -42,6 +42,13 @@ Do NOT invoke for:
 **conventions 注入（v0.11 §33）**：
 - 读取 conventions 配置，注入为需求分析上下文
 
+**项目模式确认（multi-repo-support-design v1.0 §3.3，2026-08-21）**：S1 路由时确认项目布局，写 config 供 detect/review/isolate 按模式路由——
+1. 定位项目根（`detectWorkspaceRoot` / `getGitRoot`）；`<项目根>/.team-flow/team-flow.config.json` 已有 `repo_layout` 段 → 直接读取（已固化跳过）
+2. 否则运行 `tf repo-layout detect <项目根>`：判定 `single`/`monorepo`/`multi-repo` + 代码仓库清单，写 `<项目根>/.team-flow/team-flow.config.json` 的 `repo_layout` 段
+3. 多仓库项目向用户展示判定结果（AskUserQuestion 确认）；单仓库自动；修正 repos 清单编辑 config 的 `repo_layout.repos`
+4. 影响：detect（按仓库清单探测 GLAF4）/ review（`--repo` 放宽 git 约束）/ isolate（共享分支检测）
+5. 边界：本步骤识别存量结构；全新项目骨架引导归 workflow-bootstrap B1.5
+
 ### S2: PRD + 原型阶段
 
 **⛔ MANDATORY：执行S2阶段前，必须先读取 `references/s2-prd-prototype-loop.md`**
@@ -66,7 +73,7 @@ prd_draft → user_review → prototype_loop → prd_frozen → completed
 - **错误行为**：PRD草稿完成后直接标记S3阶段完成
 - **正确行为**：PRD草稿完成后等待用户查看，确认后继续S2阶段的后续步骤
 
-调用 `/ce-brainstorm`（mode: orchestrated）产出 PRD 草稿；**冻结前派 `prd-completeness-reviewer` 子代理做 PRD 完整性评审**（v0.15.0，管"说得全不全"）；原型循环由编排层直接编排（prototype skill 内部编排产出 → prototype-reviewer 自动评审 → 人工评审 → 冻结）；冻结语义为 `frozen_downstream`（迭代内变更不升版）。反馈环路检查点：scope 是否合理。详见 `references/s2-prd-prototype-loop.md`。
+调用 `/ce-brainstorm`（mode: orchestrated）产出 PRD 草稿（Phase 3 由 prd-writer agent 契约级撰写，v0.47）；**冻结前派 `prd-completeness-reviewer` 子代理做 PRD 完整性评审**（v0.15.0，管"说得全不全"；v0.47 并入 §8.4 契约级细节 D6 维度）；原型循环由编排层直接编排（prototype skill 内部编排产出 → prototype-reviewer 自动评审 → 人工评审 → 冻结）；冻结语义为 `frozen_downstream`（迭代内变更不升版）。反馈环路检查点：scope 是否合理。详见 `references/s2-prd-prototype-loop.md`。
 
 ### ARCH: 产品级架构设计（v0.36.0 新增；2026-08-19 LT 调整上移 S3 前——S3 计划/S4 拆分是最终任务拆分，须基于架构）