@xulthekl/team-flow 0.49.0 → 0.51.0

package/scripts/guard/checks/tasks-gate-exemptions.mjs

@@ -0,0 +1,49 @@
+// scripts/guard/checks/tasks-gate-exemptions.mjs — v0.22 §85 tasks-complete 门禁豁免
+//
+// 背景（workflow-feedback 20260909-103500-guard）：
+// hotfix/tweak 跳过 spec-writer（workflow-start SKILL.md:172/173），tasks.md 的任务文本
+// 无原生产出者；而 guard 的 executing:closing 仍考核 tasks-complete（guard.mjs:75/82）。
+// 修复前该矛盾导致 closing 死锁，只能由编排层补录 tasks.md 绕过。
+//
+// 本模块与 test-gate-exemptions.mjs 同构：显式跳过优于静默豁免（v0.13 §48 原则），
+// 跳过必须附理由才放行；存量 change（无 schema_version）沿用 legacy 豁免。
+import { isLegacyChange } from './test-gate-exemptions.mjs';
+
+export { isLegacyChange };
+
+/** v0.22 §85：显式跳过 tasks.md 且理由非空（可审计豁免）。 */
+export function hasExplicitTasksSkip(state) {
+  return state?.tasks_skipped === 'true'
+    && typeof state?.tasks_skip_reason === 'string'
+    && state.tasks_skip_reason.trim().length > 0;
+}
+
+/** skip 已置但理由缺失 → 门禁拒绝并引导补理由。 */
+export function tasksSkipMissingReason(state) {
+  return state?.tasks_skipped === 'true' && !hasExplicitTasksSkip(state);
+}
+
+/**
+ * v0.22 §85.4（LT 2026-09-09 决策）：`tasks_skipped` 仅对 hotfix/tweak 合法。
+ * full 的 tasks.md 是 spec-writer 核心产物，必然产出——缺失即流程异常，应 FAIL 暴露而非豁免掩盖。
+ * `auto`/缺失归一化为 full（与 cmd-state.mjs:163 的 auto→full 归一化同口径，安全侧默认）。
+ * 无存量风险：tasks_skipped 是 v0.50.0 新字段。
+ */
+export function isFullWorkflow(state) {
+  const workflow = state?.workflow;
+  return workflow == null || workflow === '' || workflow === 'auto' || workflow === 'full';
+}
+
+/** full/auto 置了 skip → 拒绝，并给出两条可操作出路（不是死锁）。 */
+export function fullWorkflowSkipViolation(state) {
+  return state?.tasks_skipped === 'true' && isFullWorkflow(state);
+}
+
+export const TASKS_SKIP_REASON_HINT =
+  'tasks_skipped=true requires tasks_skip_reason — record it: '
+  + "tf state set <dir> tasks_skip_reason '<why this change needs no tasks.md>'";
+
+export const TASKS_SKIP_FULL_FORBIDDEN_HINT =
+  'tasks_skipped is only valid for hotfix/tweak — full workflow must produce tasks.md. '
+  + 'Either produce tasks.md, or, if this change is truly a hotfix/tweak, '
+  + 'declare the mode first: tf state set <dir> workflow <hotfix|tweak>';

package/scripts/lib/arch-merge.mjs

@@ -18,14 +18,14 @@
 import {
   readFileSync, writeFileSync as fsWriteFileSync, existsSync, mkdirSync, readdirSync, rmdirSync, cpSync,
 } from 'node:fs';
-import { join, basename, dirname, resolve } from 'node:path';
+import { join, basename, dirname, relative, 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';
+import { detectWorkspaceRoot, getGitRoot, parsePorcelainPaths } from './git-utils.mjs';
 
 const MARKER_BEGIN = '<!-- arch:current-state:begin -->';
 const MARKER_END = '<!-- arch:current-state:end -->';
@@ -420,8 +420,29 @@ function gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun)
     for (const f of touchedFiles) {
       execFileSync('git', ['add', f], { cwd: projectRoot, stdio: 'pipe' });
     }
-    execFileSync('git', ['commit', '-m', commitMsg], { cwd: projectRoot, stdio: 'pipe' });
-    return { committed: true, message: commitMsg };
+    // v0.23 §93.3.2：commit 必须带 pathspec——裸 `git commit` 提交索引中**全部已暂存内容**，
+    // 索引里若有他人/前序工具（如 tf publish --arch）留下的 staged 文件会被一并卷走。
+    execFileSync('git', ['commit', '-m', commitMsg, '--', ...touchedFiles], { cwd: projectRoot, stdio: 'pipe' });
+
+    // v0.23 §93.3.3：回读实际提交清单与白名单比对（第二道防线，不阻断——提交已完成）
+    // 前提：projectRoot 即 git 仓根（`git show --name-only` 输出仓根相对路径，此处按 projectRoot
+    // 还原为绝对路径）。projectRoot 取自 detectWorkspaceRoot(changeDir) || getGitRoot(changeDir)，
+    // 实践中成立；显式传 --project-root 指向子目录时该前提不成立，会误报为白名单外（已知边界）。
+    const committed = String(execFileSync(
+      'git', ['show', '--name-only', '--format=', 'HEAD'],
+      { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    )).split('\n').filter(Boolean).map(p => resolve(projectRoot, p));
+    const whitelist = new Set(touchedFiles.map(p => resolve(projectRoot, p)));
+    const unexpected = committed.filter(p => !whitelist.has(p));
+    if (unexpected.length > 0) {
+      console.warn(`  [WARN] 本次 commit 含白名单外的文件（${unexpected.length} 个）：${unexpected.map(p => relative(projectRoot, p)).join(', ')}`);
+    }
+    return {
+      committed: true,
+      message: commitMsg,
+      files: committed.map(p => relative(projectRoot, p)),
+      unexpected,
+    };
   } catch (e) {
     return { committed: false, error: e.message };
   }
@@ -433,10 +454,11 @@ function detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles) {
     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));
-    return dirty;
+    // v0.23 §93.3.1：改用共享解析器。原 `^\S+\s+` 无法剥离 ` M path`（行首空格 = 未暂存修改，
+    // 最常见形态）→ 路径残留状态码 → 本次 touch 的文件被误报为「非本次 touch 的脏文件」。
+    // 路径口径统一为「相对 projectRoot 的绝对路径」后再与白名单比对，不依赖 process.cwd()。
+    const touched = new Set(touchedFiles.map(p => resolve(projectRoot, p)));
+    return parsePorcelainPaths(status).filter(p => p && !touched.has(resolve(projectRoot, p)));
   } catch {
     return [];
   }
@@ -533,7 +555,8 @@ export function run(args = {}) {
     ].filter(p => existsSync(p));
     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 不卷走它们，但请确认是否他人未提交工作`);
+      console.warn(`  [WARN] docs/architecture/ 检测到 ${dirty.length} 个非本次 touch 的改动：${dirty.slice(0, 5).join(', ')}${dirty.length > 5 ? ' …' : ''}`);
+      console.warn(`         本次提交范围以白名单为准（${touchedFiles.length} 个文件）；上述文件不会被提交，请确认是否他人未提交工作。`);
     }
     const commitResult = gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun);
 

package/scripts/lib/arch-precheck.mjs

@@ -0,0 +1,190 @@
+// scripts/lib/arch-precheck.mjs — tf arch precheck：架构判断门的确定性证据工具（v0.22 §88.3.2）
+//
+// 定位：**证据工具，不是判断者**。本命令只输出"架构信号命中情况"，
+// 判断仍归 architecture-design 子代理（v0.9 §26 的独立性不变）。
+// 退出码恒为 0 —— 不阻断流程，也不替代判断。
+//
+// 动机（workflow-feedback 20260909-112755）：hotfix 对表现层文案改动跑完整架构门
+// 消耗 41,864 tk，结论必然 skipped。让子代理在 signal=none 时只读 brief + 本命令输出
+// （不读全量 docs/architecture/）可大幅降本，同时保留独立判断与回退能力。
+//
+// 设计约束（H1 实测校准）：
+//   - 关键词须为**高置信度**短语——裸 `schema` / `api` 会误命中测试矩阵术语（"schema 覆盖声明"）
+//   - 否定表述须识别——"不动 filter.args" / "无聚合" 是**负向**证据，不能计为命中
+//   - 文件提取须去噪——`node_modules/` 引用非改动文件；同名文件按最完整路径去重
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 架构关键词表（对应 architecture-design SKILL 五项检查 + 配置契约 key）。 */
+const ARCH_KEYWORDS = [
+  // 1 聚合
+  '聚合', '聚合根', 'aggregate',
+  // 2 限界上下文
+  '限界上下文', 'bounded context',
+  // 3 读写模型
+  '读写模型', 'cqrs', '写模型', '读模型',
+  // 4 API（精确短语，避免裸 api 假阳性）
+  'api 签名', 'api 端点', 'api 变更', 'api 新增', '新增 api', 'api 契约', 'endpoint', '端点',
+  // 5 DB schema（精确短语，避免裸 schema 误命中测试矩阵术语）
+  'db schema', '数据库 schema', '表结构', 'ddl', '数据库表', '索引变更',
+  // 配置契约 key
+  'filter.args',
+];
+
+/**
+ * 否定上下文（行级）：否定词可能出现在关键词**之后**同句（如"范围外…`filter.args` …一律不动"）。
+ * 宽松匹配是刻意的——误判为 negated 只会让门走完整路径（安全），
+ * 误判为 positive 才会放行 fast path（危险）。
+ */
+const LINE_NEGATION_RE = /(不动|不涉及|不变更|不新增|不修改|不改变|不调整|不包含|严禁|不得|禁止|零变更|无变更|无新增|无修改|保持不变|unchanged|no change|without)/i;
+const NEGATION_ADJACENT_RE = /(不|无|非|未|零|no|not)\s*$/;
+
+/**
+ * 变更语境：关键词前文出现变更动词才计为**正向**信号。
+ * 仅"提到"关键词（如"按 filter.args 断言写回"）属中性，不构成架构变更信号。
+ */
+const CHANGE_VERB_RE = /(新增|修改|变更|调整|增加|删除|引入|扩展|重构|改造|迁移|升级|add|new|modify|change|update|refactor|migrate)/i;
+
+const PRESENTATION_EXTS = new Set(['.vue', '.jsx', '.tsx', '.less', '.css', '.scss', '.sass', '.html']);
+const BACKEND_EXTS = new Set(['.java', '.go', '.py', '.rb', '.rs', '.kt', '.kts', '.cs']);
+const CONFIG_EXTS = new Set(['.yaml', '.yml', '.json', '.sql', '.toml', '.ini', '.properties']);
+const SCRIPT_EXTS = new Set(['.js', '.ts', '.mjs', '.cjs', '.mts', '.cts']);
+const TEST_PATTERNS = [
+  /\.spec\.[cm]?[jt]sx?$/i,
+  /\.test\.[cm]?[jt]sx?$/i,
+  /Tests?\.java$/,
+  /_test\.go$/i,
+  /^test_.*\.py$/i,
+  /Tests?\.(kt|cs)$/,
+];
+
+const CODE_EXT_PATTERN = [...PRESENTATION_EXTS, ...BACKEND_EXTS, ...CONFIG_EXTS, ...SCRIPT_EXTS]
+  .map(e => e.slice(1))
+  .sort((a, b) => b.length - a.length)
+  .join('|');
+
+const FILE_RE = new RegExp(`(?:[\\w.-]+/)*[\\w.-]+\\.(?:${CODE_EXT_PATTERN})(?![\\w])`, 'gi');
+
+function classifyFile(file) {
+  const ext = path.extname(file).toLowerCase();
+  const base = path.basename(file);
+  if (TEST_PATTERNS.some(re => re.test(base))) return 'test';
+  if (PRESENTATION_EXTS.has(ext)) return 'presentation';
+  if (BACKEND_EXTS.has(ext)) return 'backend';
+  if (CONFIG_EXTS.has(ext)) return 'config';
+  if (SCRIPT_EXTS.has(ext)) return 'script';
+  return 'other';
+}
+
+/** 文件提取：剔除 node_modules 引用，同名文件保留最完整路径。 */
+function extractFiles(text) {
+  const byBase = new Map();
+  for (const m of text.matchAll(FILE_RE)) {
+    const f = m[0];
+    if (/(^|\/)node_modules\//.test(f)) continue;
+    const base = path.basename(f);
+    const prev = byBase.get(base);
+    if (!prev || f.length > prev.length) byBase.set(base, f);
+  }
+  return [...byBase.values()];
+}
+
+/** 关键词逐次出现的语境统计：negated（否定）/ positive（变更动词）/ neutral（仅提及）。 */
+function findKeyword(text, keyword) {
+  const kw = keyword.toLowerCase();
+  const stat = { occurrences: 0, positive: 0, negated: 0, neutral: 0 };
+  for (const line of text.split('\n')) {
+    const lowerLine = line.toLowerCase();
+    let idx = lowerLine.indexOf(kw);
+    while (idx !== -1) {
+      stat.occurrences += 1;
+      const before = line.slice(Math.max(0, idx - 30), idx);
+      if (LINE_NEGATION_RE.test(line) || NEGATION_ADJACENT_RE.test(before)) stat.negated += 1;
+      else if (CHANGE_VERB_RE.test(before)) stat.positive += 1;
+      else stat.neutral += 1;
+      idx = lowerLine.indexOf(kw, idx + kw.length);
+    }
+  }
+  return stat;
+}
+
+/**
+ * 扫描 change 的规划制品，返回架构信号证据。
+ * @returns {{ signal: 'none'|'weak'|'strong', hits: object, evidence: string[], sources: string[] }}
+ */
+export function collectArchSignals(changeDir) {
+  const sources = [];
+  for (const name of ['change-brief.md', 'execution-contract.md']) {
+    const p = path.join(changeDir, name);
+    if (fs.existsSync(p)) sources.push({ name, text: fs.readFileSync(p, 'utf-8') });
+  }
+
+  const text = sources.map(s => s.text).join('\n');
+
+  const keywords = [];
+  const negated = [];
+  const neutral = [];
+  for (const kw of ARCH_KEYWORDS) {
+    const stat = findKeyword(text, kw);
+    if (stat.occurrences === 0) continue;
+    if (stat.positive > 0) keywords.push(kw);
+    else if (stat.negated > 0) negated.push(kw);
+    else neutral.push(kw);
+  }
+
+  const files = { presentation: [], backend: [], config: [], script: [], test: [], other: [] };
+  for (const f of extractFiles(text)) files[classifyFile(f)].push(f);
+
+  const hasSql = files.config.some(f => f.toLowerCase().endsWith('.sql'));
+
+  let signal;
+  if (keywords.length > 0) signal = 'strong';
+  else if (files.backend.length > 0 || hasSql) signal = 'weak';
+  else if (files.presentation.length > 0) signal = 'none';
+  else signal = 'weak';
+
+  const evidence = [];
+  if (sources.length === 0) {
+    evidence.push('no change-brief.md / execution-contract.md found — signal defaults to weak');
+  }
+  evidence.push(keywords.length === 0
+    ? 'no architecture keyword in change context'
+    : `architecture keyword in change context: ${keywords.join(', ')}`);
+  if (negated.length > 0) evidence.push(`negated (not a signal): ${negated.join(', ')}`);
+  if (neutral.length > 0) evidence.push(`mentioned without change context (not a signal): ${neutral.join(', ')}`);
+  evidence.push(
+    `code files — presentation=${files.presentation.length}, backend=${files.backend.length}, `
+    + `config=${files.config.length}, script=${files.script.length}, test=${files.test.length}`,
+  );
+  if (signal === 'none') {
+    evidence.push('all evidence points to presentation-layer only — fast-path candidate (sub-agent must still confirm)');
+  }
+
+  return {
+    signal,
+    hits: { keywords, negatedKeywords: negated, neutralKeywords: neutral, files },
+    evidence,
+    sources: sources.map(s => s.name),
+  };
+}
+
+export async function run(positionals, values) {
+  const changeDirArg = positionals[0];
+  if (!changeDirArg) {
+    console.error('Usage: tf arch precheck <change-dir> [--json]');
+    process.exit(2);
+  }
+  const changeDir = path.resolve(changeDirArg);
+  const result = collectArchSignals(changeDir);
+
+  if (values.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`arch precheck — signal: ${result.signal}`);
+    console.log(`  sources: ${result.sources.join(', ') || '(none)'}`);
+    for (const line of result.evidence) console.log(`  - ${line}`);
+    console.log('  note: evidence only — the architecture-design sub-agent still makes the decision.');
+  }
+  // 证据工具：恒以 0 退出，不阻断流程。
+  process.exit(0);
+}

package/scripts/lib/cmd-arch.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
+import * as archPrecheck from './arch-precheck.mjs';
 
 const ARCH_STATE_FILE = '.team-flow/arch-state.json';
 
@@ -16,6 +17,7 @@ export async function run(args) {
       'project-root': { type: 'string' },
       mode: { type: 'string', default: 'reconstruction' },
       'baseline-ref': { type: 'string', default: 'prd/vN/' },
+      json: { type: 'boolean', default: false },
     },
     allowPositionals: true,
   });
@@ -23,7 +25,9 @@ export async function run(args) {
   const sub = positionals[0];
   if (sub === 'init') return init(values);
   if (sub === 'show') return show(values);
-  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show');
+  // v0.22 §88.3.2：架构门判据的确定性证据工具（证据 only，退出码恒 0）
+  if (sub === 'precheck') return archPrecheck.run(positionals.slice(1), values);
+  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch precheck <change-dir> [--json]');
   process.exit(2);
 }
 

package/scripts/lib/cmd-deisolate.mjs

@@ -15,10 +15,10 @@
 //   Case B 单仓库：<change-dir> 同级 ../<repo>-<change-name> 存在
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { existsSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { detectWorkspaceRoot } from './git-utils.mjs';
+import { detectWorkspaceRoot, listCodeReposDeep } from './git-utils.mjs';
 
 export async function run(args) {
   const { positionals, values } = parseArgs({
@@ -79,24 +79,23 @@ export async function run(args) {
 }
 
 
-// Case A: <root>/.worktrees/<change>/<repo>/
+// Case A: <root>/.worktrees/<change>/<repo>/ 或 <root>/.worktrees/<change>/<container>/<repo>/
+// v0.23 §92.3.7（P4 plugin-validator M1）：复用两层探测——ensure-branch 现按 relPath 建 worktree，
+// 嵌套布局（service/<repo>）在 <change>/ 下的直接子项是容器目录（无 .git），旧的一层扫描会漏检
+// → deisolate 报 "No worktrees found"，closing 阶段代码永远停在 worktree 分支。
 function detectCaseA(root, changeName) {
   const changeWorktreeDir = join(root, '.worktrees', changeName);
   if (!existsSync(changeWorktreeDir)) return null;
 
-  let entries;
-  try {
-    entries = readdirSync(changeWorktreeDir, { withFileTypes: true });
-  } catch {
-    return null;
-  }
-
-  const repos = entries
-    .filter(e => e.isDirectory() && existsSync(join(changeWorktreeDir, e.name, '.git')))
-    .map(e => ({
-      name: e.name,
-      worktreePath: join(changeWorktreeDir, e.name),
-      repoPath: join(root, e.name),
+  // excludeNonRepoDirs: false —— worktree 目录结构由 ensure-branch 按 config 权威清单创建，
+  // 仓名可能恰是 NON_REPO_DIRS 中的词（data / prototype / docs / …）；沿用探测期排除表会漏检
+  // → 代码静默留在 worktree 分支（P4 plugin-validator 复审残留 M1）。
+  const repos = listCodeReposDeep(changeWorktreeDir, { excludeNonRepoDirs: false })
+    .map(repo => ({
+      // 用 relPath 作展示名：嵌套布局下可区分 service/a 与 service/b（扁平布局等价于目录名）
+      name: repo.relPath,
+      worktreePath: join(changeWorktreeDir, repo.relPath),
+      repoPath: join(root, repo.relPath),
       layout: 'A',
     }))
     .sort((a, b) => a.name.localeCompare(b.name));

package/scripts/lib/cmd-doctor.mjs

@@ -5,6 +5,8 @@ import { loadConfig } from './config-loader.mjs';
 import { PLATFORM_RUNTIME_INVENTORY } from './platform-runtime-inventory.mjs';
 // 非法 state 巡检所需的共享常量与读取器(来源:workflow-feedback 2026-08-01,#100004)。
 import { readState, VALID_STATES } from './state-loader.mjs';
+// v0.22 §85：tasks_skipped 豁免判定复用 guard 侧唯一真相源，避免同一规则两处实现漂移。
+import { hasExplicitTasksSkip } from '../guard/checks/tasks-gate-exemptions.mjs';
 
 const RUNTIME_SKILLS = new Set([
   'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
@@ -258,8 +260,8 @@ function checkChangeStates(root) {
   return { pass: true, message: `${checked} change(s) have legal state values` };
 }
 
-// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）：
-// 1. test_matrix_skipped=true 必须附 test_matrix_skip_reason（可审计豁免）；
+// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）；v0.22 §85 扩展 tasks_skipped：
+// 1. test_matrix_skipped / tasks_skipped = true 必须附对应 reason（可审计豁免）；
 // 2. 状态引用的产物文件必须存在（arch_review_report / test_evidence_path）——
 //    C1 现场曾出现 arch_review_report 指向不存在的 auto-review.md。
 // DP 时间戳顺序检查评估后未纳入：closing 后的 DP-7 时间戳晚于 last_transition 属合法，
@@ -283,6 +285,11 @@ function checkChangeTestGates(root) {
       && !(typeof state.test_matrix_skip_reason === 'string' && state.test_matrix_skip_reason.trim())) {
       issues.push(`${d}: test_matrix_skipped=true without test_matrix_skip_reason`);
     }
+    // v0.22 §85：tasks_skipped 沿用同一可审计豁免范式（跳过必须附理由），
+    // 判定复用 tasks-gate-exemptions 的共享谓词（与 guard 同一真相源）。
+    if (state.tasks_skipped === 'true' && !hasExplicitTasksSkip(state)) {
+      issues.push(`${d}: tasks_skipped=true without tasks_skip_reason`);
+    }
     for (const field of ['arch_review_report', 'test_evidence_path']) {
       const ref = state[field];
       if (typeof ref === 'string' && ref.trim() && !existsSync(join(changeDir, ref))) {

package/scripts/lib/cmd-publish.mjs

@@ -19,7 +19,7 @@
 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';
+import { detectWorkspaceRoot, parsePorcelainPaths } from './git-utils.mjs';
 
 const LOCK_PATH = '.publish.lock';
 
@@ -126,12 +126,9 @@ function detectOutsideDirty(projectRoot, whitelist) {
   try {
     const status = git(projectRoot, 'status', '--porcelain');
     if (!status) return [];
-    return status.split('\n').filter(Boolean)
-      .map(line => {
-        // porcelain 前 2 字符是状态，后面是路径（引号包裹的可能带空格）
-        const raw = line.slice(3).replace(/^"|"$/g, '').replace(/\\ /g, ' ');
-        return raw;
-      })
+    // v0.23 §93.3.1：解析统一走 git-utils.parsePorcelainPaths（本文件的 slice(3) 实现
+    // 是正确版本，已上移共享；arch-merge 原用的 `^\S+\s+` 正则会漏掉 ` M path`）。
+    return parsePorcelainPaths(status)
       .filter(p => {
         if (!p) return false;
         const norm = p.replace(/\/+$/, ''); // porcelain 目录级输出带尾斜杠，先去规范化

package/scripts/lib/cmd-state.mjs

@@ -38,6 +38,8 @@ const SETTABLE_FIELDS = [
   'compound_skipped',
   // Test matrix gate (v0.12 §45.4 + v0.13 §48.2)
   'test_matrix_skipped', 'test_matrix_skip_reason',
+  // Tasks gate (v0.22 §85：hotfix/tweak 显式跳过 tasks.md，须附理由)
+  'tasks_skipped', 'tasks_skip_reason',
 ];
 
 export async function run(args) {

package/scripts/lib/conventions-generator.mjs

@@ -13,6 +13,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from
 import { homedir } from 'node:os';
 import path, { join } from 'node:path';
 import { parseArgs } from 'node:util';
+import { listCodeReposDeep, NON_REPO_DIRS } from './git-utils.mjs';
 
 // ── glaf4-dev 运行时探测（v2.1 §4 接口①）─────────────────────────────────────
 
@@ -109,11 +110,7 @@ export function writeGlaf4DevConfig(root, glaf4DevInfo) {
 
 // ── 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',
-]);
+// 非代码仓库目录集合统一在 git-utils.mjs 定义（v0.23 §92：唯一真相源），见顶部 import。
 
 /**
  * 识别项目布局（single / monorepo / multi-repo，v1.0 §3.1）
@@ -130,15 +127,20 @@ export function detectRepoLayout(root) {
     return { mode: subModules.length > 0 ? 'monorepo' : 'single', repos };
   }
   // 2. 根无技术栈特征 → 扫描子目录识别独立代码仓库（含 .git 或有技术栈语言）
+  // v0.23 §92.3.3：含 .git 的仓库改用 listCodeReposDeep 探测，支持 `service/<repo>` 两层布局
+  //（原实现只扫直接子项 → emp-auth 12 仓被误判 single，config 靠人工修正）。
   const repos = {};
+  for (const repo of listCodeReposDeep(root)) {
+    repos[repo.relPath] = repo.absPath;
+  }
   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;
+    if (repos[entry.name]) continue;
     const sub = join(root, entry.name);
-    const hasGit = existsSync(join(sub, '.git'));
     const tech = detectTechStack(sub);
-    if (hasGit || tech.language) {
+    if (tech.language) {
       repos[entry.name] = sub;
     }
   }

package/scripts/lib/execution-plan.mjs

@@ -5,7 +5,8 @@ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { computeArtifactsHash, computeContractHash, hashObject, stableJson } from './hash.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { readState } from './state-loader.mjs';
-import { detectWorkspaceRoot, findSubRepo } from './git-utils.mjs';
+import { detectWorkspaceRoot, findSubRepo, resolveCodeRepos } from './git-utils.mjs';
+import { loadConfig } from './config-loader.mjs';
 
 // v2.1 §6.6：扩入 glaf4-delegation（GLAF4 change 整体委托 glaf4-dev 七模式流，S1 结构统一）
 export const EXECUTION_MODES = ['inline', 'batch-inline', 'sdd', 'glaf4-delegation'];
@@ -334,8 +335,22 @@ function validateReviewRange(changeDir, base, head, repoPath) {
     const workspaceRoot = detectWorkspaceRoot(changeDir);
     if (!workspaceRoot) throw primaryError;
 
-    const subRoot = findSubRepo(workspaceRoot, head);
-    if (!subRoot) throw primaryError;
+    // v0.23 §92.3.4：传入 config（repo_layout 权威 + 两层探测）
+    const config = loadConfig(workspaceRoot);
+    const subRoot = findSubRepo(workspaceRoot, head, config);
+    if (!subRoot) {
+      // v0.23 §92.3.5：文案区分「SHA 不存在」与「不在已扫描仓中」——后者给出扫描清单与 --repo 指引
+      const { repos, unresolved, source } = resolveCodeRepos(workspaceRoot, config);
+      const scanned = repos.length ? repos.map(r => r.relPath).join(', ') : '(none)';
+      throw new Error(
+        `${primaryError.message}\n`
+        + `  Scanned repos (source=${source}, ${repos.length}): ${scanned}\n`
+        + (unresolved.length
+          ? `  Unresolved repo_layout.repos entries (${unresolved.length}): ${unresolved.map(u => u.key).join(', ')}\n`
+          : '')
+        + '  If the commit lives in a nested repo not listed above, pass --repo <abs-path>.',
+      );
+    }
 
     resolvedBase = resolveGitCommit(subRoot, base, 'base');
     resolvedHead = resolveGitCommit(subRoot, head, 'head');