@xulthekl/team-flow 0.50.0 → 0.51.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.50.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.51.0 | 阶段: {{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 + independent business analysis. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.50.0",
+      "version": "0.51.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "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.50.0"
+    "version": "0.51.0"
   },
   "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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "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.50.0"
+    "version": "0.51.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.50.0",
+      "version": "0.51.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.51.0] - 2026-09-09
+
+### Fixed（CLI 静默失效治理：仓清单 / 白名单 / 严重度序）
+
+设计来源：`docs/architecture-api-db-design-enhancement-v0.23.md` §91-§93（2026-09-09，emp-auth 4 条 workflow-feedback：20260909-101814 / 101815 / 101816 / 104554）
+
+**R1 — severity 有序等级集中化**（`tf solutions promote` 漏晋升 critical）
+
+- **唯一真相源**：新增 `scripts/lib/severity.mjs`（`SEVERITY_ORDER` / `SEVERITY_LADDER` / `severityRank` / `meetsMinSeverity` / `nextSeverity`），取值域扩展为 `critical | high | medium | low`
+- **修复三处同时失效**：晋升判定用集合相等 `severity === 'high' || 'medium'` → `meetsMinSeverity(severity, 'medium')`；升级阶梯补 critical 封顶；`SEVERITY_ORDER` 两处重复定义删除并补 critical 键（原先 critical 排序垫底、inject top-5 优先排除）
+- **入口闸**：`tf solutions capture --severity` 新增取值校验（非法值报错并列出合法取值）
+- **防模板污染**：`parseFrontmatter` 剥离行尾注释（模板注释被逐字复制时会污染取值）
+- 规范同步：`templates/learnings.md` / `release-archivist`（SKILL + closing-procedures）/ `ce-compound`（promotion-rules + three-tier-index + write-flow）
+
+**R2 — 仓清单解析统一**（`tf execution review` 嵌套仓找不到、`tf isolate` 静默降级为空壳）
+
+- **统一入口**：`git-utils.resolveCodeRepos`（config `repo_layout.repos` 权威 → 两层探测 fallback）、`listCodeReposDeep`（支持 `service/<repo>` 等两层布局）、`parsePorcelainPaths`（porcelain 解析唯一实现）
+- **格式兼容**：`repo_layout.repos` 的 key/value 逐序尝试（相对路径 / 绝对路径 / 人类描述），命中判据为「目录存在」+ 返回 `isGitRepo` 供消费方分流
+- **禁止静默降级**：config 声明 `mode=multi-repo` 却解析不到 git 仓时 `tf isolate` 退出非 0（`--force` 可显式降级）
+- **报错可操作**：review receipt 的 SHA 不在任何已扫描仓时，报错附扫描清单与 `--repo` 指引
+- **消费者闭环**：`tf deisolate` 的 `detectCaseA` 复用两层探测（`excludeNonRepoDirs: false` 与创建方口径对齐），嵌套仓与怪名仓（`data`/`prototype`/`docs/*`）不再漏检
+- 消费方改造：`ensure-branch` / `execution-plan` / `conventions-generator`（嵌套探测）/ `glaf4-delegation`（复用解析器，修 `Object.values(repos)` 把人类描述当路径）
+
+**R3 — arch-merge 白名单机制修复**（告警与实际提交行为不一致）
+
+- **判定侧**：`detectUntouchedDirtyFiles` 改用共享 `parsePorcelainPaths`（原 `^\S+\s+` 漏匹配 ` M path`，导致本次 touch 的文件被误报为「非本次 touch 的脏文件」）
+- **提交侧**：`git commit -- <白名单>` 限定边界（裸 `git commit` 会卷走索引中已暂存的外部文件）
+- **事后断言**：回读 `git show --name-only` 与白名单比对，不一致则 WARN
+
+**质量**：P3 审查发现并修复 5 项（含 `glaf4-delegation` 设计承诺未落地）；P4 两轮评审（skill-reviewer FAIL→PASS，8 项修复；plugin-validator FAIL→FAIL→PASS，闭环 `tf deisolate` 断链与 `NON_REPO_DIRS` 口径回归）；**807/807 测试通过**。
+
 ## [0.50.0] - 2026-09-09
 
 ### Fixed（hotfix 路径死锁 + 轻量路径仪式成本）

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.50.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.51.0 | 阶段: {{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.50.0**。
+当前发布版本：**v0.51.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.50.0`
+> 当前版本：`v0.51.0`
 
 > 统一插件：**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.50.0`
+- Current: `v0.51.0`
 - 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/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) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.50.0: auto-sync CLI version with plugin version
+# v0.51.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.50.0"
+PLUGIN_VERSION="0.51.0"
 
 # ═══════════════════════════════════════════════════════════════
 # 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.50.0.
+Current version: v0.51.0.
 
 ## 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.50.0",
+  "version": "0.51.0",
   "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis 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.50.0",
+  "version": "0.51.0",
   "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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/ensure-branch.mjs

@@ -6,16 +6,19 @@
 //
 // Usage: node ensure-branch.mjs <change-dir> [change-name] [--force]
 //
-// 布局识别（来源：workflow-feedback 2026-08-01 #100009）：
-//   Case A 多仓库工作区 —— change-dir 形如 <root>/changes/<name>，且 <root> 下
-//     存在含 .git 的直接子目录（真正的业务代码仓库，如 bff-*/ui-*/prototype/）。
-//     工作区根本身往往只是近空壳 git 仓库（仅跟踪 .gitignore，无 remote）。旧实现
-//     把 change-dir 当代码仓库、worktree 建在 ../，结果是空工作区副本，实现子代理
-//     看不到任何参考代码。新实现为每个代码仓库在 <root>/.worktrees/<change>/<repo>
-//     建立 worktree（基于各仓库当前分支），实现子代理进入 <root>/.worktrees/<change>/
-//     即可看到与主工作区一致的目录结构和全部参考代码。
-//   Case B 单代码仓库（遗留兼容）—— 不满足 Case A 时回退到旧行为：把 change-dir
-//     当代码仓库，worktree 建在 ../<repo>-<name>。保证单仓库项目不被破坏。
+// 布局识别（来源：workflow-feedback 2026-08-01 #100009；v0.23 §92.3.4/§92.3.6 重构）：
+//   仓清单统一由 git-utils.resolveCodeRepos 解析（config 权威 → 两层探测 fallback），
+//   本文件不再自行枚举目录。
+//   Case A 多仓库工作区 —— change-dir 形如 <root>/changes/<name>，且解析出 ≥1 个代码仓库
+//     （含 <root>/<repo> 与 <root>/service/<repo> 两种布局）。工作区根本身往往只是近空壳
+//     git 仓库（仅跟踪 .gitignore，无 remote）。旧实现把 change-dir 当代码仓库、worktree
+//     建在 ../，结果是空工作区副本，实现子代理看不到任何参考代码。现为每个代码仓库在
+//     <root>/.worktrees/<change>/<repo> 建立 worktree（基于各仓库当前分支），实现子代理
+//     进入 <root>/.worktrees/<change>/ 即可看到与主工作区一致的目录结构和全部参考代码。
+//   Case B 单代码仓库（遗留兼容）—— 无 repo_layout 声明或声明为 single 时回退旧行为：
+//     把 change-dir 当代码仓库，worktree 建在 ../<repo>-<name>。保证单仓库项目不被破坏。
+//   硬失败（v0.23 §92.3.6）—— config 声明 mode=multi-repo 却解析不到任何代码仓库时退出
+//     非 0（此前会静默降级为 Case B，建出空壳 worktree 且代码落到共享分支）。--force 可显式降级。
 //
 // Security: every git invocation uses execFileSync with a LITERAL command
 // ('git') and a LITERAL argument array (no shell, no string-form command) — the
@@ -25,8 +28,9 @@
 // branch names are additionally sanitized to git-legal characters before use.
 import { execFileSync } from 'node:child_process';
 import { resolve, basename, join } from 'node:path';
-import { detectWorkspaceRoot } from './lib/git-utils.mjs';
-import { readdirSync, existsSync, appendFileSync, readFileSync } from 'node:fs';
+import { detectWorkspaceRoot, resolveCodeRepos } from './lib/git-utils.mjs';
+import { loadConfig } from './lib/config-loader.mjs';
+import { existsSync, appendFileSync, readFileSync } from 'node:fs';
 
 const rawChangeDir = process.argv[2];
 // 第三个位置参数是可选 change-name；若它其实是 '--force' 之类的开关则忽略，避免把
@@ -107,21 +111,6 @@ function checkSharedBranch(repoDir) {
   }
 }
 
-// 枚举 root 下含 .git 的直接子目录（= 代码仓库），按目录名排序保证确定性。
-// .git 可能是目录（普通仓库）或文件（worktree/submodule 链接），existsSync 均覆盖。
-function listCodeRepos(root) {
-  let entries;
-  try {
-    entries = readdirSync(root, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((e) => e.isDirectory() && existsSync(join(root, e.name, '.git')))
-    .map((e) => e.name)
-    .sort();
-}
-
 // 确保 <root>/.gitignore 含忽略 .worktrees/ 的行，已有则不重复追加。
 function ensureWorktreeGitignore(root) {
   const gitignorePath = join(root, '.gitignore');
@@ -300,14 +289,51 @@ function runSingleRepo() {
   process.exit(1);
 }
 
-// 主流程：布局识别后分发（来源：workflow-feedback 2026-08-01 #100009）。
+// 主流程：布局识别后分发（来源：workflow-feedback 2026-08-01 #100009；
+// v0.23 §92.3.4/§92.3.6：仓清单统一走 resolveCodeRepos，config 声明与实况矛盾时硬失败）。
 const workspaceRoot = detectWorkspaceRoot(changeDir);
-const codeRepos = workspaceRoot ? listCodeRepos(workspaceRoot) : [];
+const config = workspaceRoot ? loadConfig(workspaceRoot) : null;
+const { repos: codeRepos, unresolved, source } = workspaceRoot
+  ? resolveCodeRepos(workspaceRoot, config)
+  : { repos: [], unresolved: [], source: 'probe' };
+
+// v0.23 §92.3.2：repo_layout.repos 条目可能是 monorepo 风格的 Java 模块（无 .git），
+// 无法建 worktree —— 隔离只对 git 仓生效，非 git 条目跳过并告警（不静默）。
+const gitRepos = codeRepos.filter(r => r.isGitRepo);
+const nonGitRepos = codeRepos.filter(r => !r.isGitRepo);
 
-if (workspaceRoot && codeRepos.length > 0) {
+if (workspaceRoot && gitRepos.length > 0) {
   // Case A：多仓库工作区。
-  runMultiRepo(workspaceRoot, codeRepos);
+  if (unresolved.length > 0) {
+    console.error(`ensure-branch: ${unresolved.length} 条 repo_layout.repos 声明无法解析为路径（已忽略）：`
+      + unresolved.map(u => `\n    - ${u.key}`).join(''));
+  }
+  if (nonGitRepos.length > 0) {
+    console.error(`ensure-branch: ${nonGitRepos.length} 个声明项非 git 仓库（无法建 worktree，已跳过隔离）：${nonGitRepos.map(r => r.relPath).join(', ')}`);
+  }
+  console.error(`ensure-branch: repo list resolved from ${source}（${gitRepos.length} 个）: ${gitRepos.map(r => r.relPath).join(', ')}`);
+  runMultiRepo(workspaceRoot, gitRepos.map(r => r.relPath));
+} else if (config?.repo_layout?.mode === 'multi-repo') {
+  // v0.23 §92.3.6：config 声明 multi-repo 却解析不到任何代码仓库 → 硬失败，禁止静默降级。
+  // 历史缺陷：此时会走 Case B，把 change-dir 当代码仓库、建出归属根仓的空壳 worktree，
+  // 实现子代理回到主工作区直接改共享分支（emp-auth feedback 2026-09-09）。
+  console.error('ensure-branch: config 声明 repo_layout.mode=multi-repo，但未解析出任何代码仓库 —— 拒绝按单仓库就地实施。');
+  console.error(`  workspace root : ${workspaceRoot}`);
+  console.error(`  config         : ${join(workspaceRoot, '.team-flow', 'team-flow.config.json')}`);
+  if (unresolved.length > 0) {
+    console.error(`  无法解析的声明（${unresolved.length} 条）：${unresolved.map(u => u.key).join(', ')}`);
+    console.error('  提示：key 应为相对工作区根的仓库路径（如 service/infra-emp-auth），或 value 为仓库绝对路径。');
+  } else {
+    console.error('  提示：repo_layout.repos 为空，或路径未指向含 .git 的目录；可运行 tf repo-layout detect 重建。');
+  }
+  console.error('  如确认要在共享分支就地实施，请显式传 --force。');
+  if (!force) process.exit(1);
+  console.error('ensure-branch: WARNING — --force given; falling back to single-repo behavior.');
+  runSingleRepo();
 } else {
-  // Case B：不满足 Case A → 回退单代码仓库行为，保证单仓库项目不被破坏。
+  // Case B：真单仓库（无 config，或 config.mode=single）→ 保持既有行为。
+  if (!config?.repo_layout?.mode) {
+    console.error('ensure-branch: 未检测到 repo_layout 配置，按单仓库处理；多仓库项目请先运行 tf repo-layout detect <root>。');
+  }
   runSingleRepo();
 }

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/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-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/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');

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/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（晋升时保留）
 ---

package/skills/ce-compound/references/write-flow.md

@@ -10,7 +10,7 @@
 ## 淘汰规则（Eviction）
 
 当 INDEX.md 超过 150 行硬上限时：
-- 按 severity 降序排列（high > medium > low）
+- 按 severity 降序排列（critical > high > medium > low；序定义于 `scripts/lib/severity.mjs`）
 - 保留前 150 条
 - 淘汰 low severity 且 date 最早的条目
 - 被淘汰的经验文件保留在阶段目录中（可从文件系统找回），仅从 INDEX.md 移除

package/skills/release-archivist/SKILL.md

@@ -207,7 +207,9 @@ tf solutions promote <change-dir>
 
 This checks the change's `learnings.md` (change root; v0.49.0 §83.3.5 path unification) for entries meeting promotion criteria:
 - severity ≥ medium AND type = pitfall/pattern → promote to global `docs/solutions/`
-- domain+type matches existing global entry → mark as "confirmed pattern", upgrade severity
+- domain+type matches existing global entry → mark as "confirmed pattern", upgrade severity (low → medium → high → critical)
+
+Valid `severity` values: `critical` | `high` | `medium` | `low` (ordered; lowercase, case-sensitive; v0.23 §91 — the order is defined once in `scripts/lib/severity.mjs`).
 
 Report promotion results in the closing summary. Promotion is advisory — failures do not block closing.
 

package/skills/release-archivist/references/closing-procedures.md

@@ -26,7 +26,7 @@ tf solutions promote <change-dir>
 
 Promotion criteria:
 - severity ≥ medium AND type = pitfall/pattern → promote to global `docs/solutions/`
-- domain+type matches existing global entry → mark as "confirmed pattern", upgrade severity
+- domain+type matches existing global entry → mark as "confirmed pattern", upgrade severity (low → medium → high → critical)
 
 Report promotion results in the closing summary. Promotion is advisory — failures do not block closing.
 

package/skills/release-archivist/references/worktree-merge.md

@@ -25,7 +25,7 @@ team-flow 的 change 实施在 worktree 隔离环境（`tf isolate` → `.worktr
 
 ## 多仓库策略（Case A）
 
-多仓库工作区（bff/ui 等独立 git 仓库）中，`tf deisolate` 自动识别 Case A 布局（`.worktrees/<change>/<repo>/`），逐 repo 执行合并。每个独立仓库是一个独立 git 操作，互不依赖。
+多仓库工作区（bff/ui 等独立 git 仓库）中，`tf deisolate` 自动识别 Case A 布局（`.worktrees/<change>/<repo>/`，含 `service/<repo>` 两层嵌套，v0.23 §92.3.7），逐 repo 执行合并。每个独立仓库是一个独立 git 操作，互不依赖。
 
 ## 依赖链顺序
 

package/templates/learnings.md

@@ -16,7 +16,7 @@
 phase: cross-phase        # 阶段名（prd/plan/architecture/prototype/spec/build/review/cross-phase）或具体领域阶段
 domain: <领域>            # 如 jest / sdd / spring-boot；注入时按领域过滤
 type: pitfall             # pitfall | pattern | insight
-severity: medium          # high | medium | low
+severity: medium          # critical | high | medium | low（小写；critical = 安全/数据/合规级高危经验）
 date: YYYY-MM-DD
 ---
 
@@ -45,7 +45,7 @@ date: YYYY-MM-DD
 | 条件 | 行为 |
 |---|---|
 | `severity` ≥ medium 且 `type` = pitfall / pattern | 晋升到全局 `docs/solutions/<phase>/`，并追加 INDEX 行 |
-| 与全局 INDEX 已有条目 domain + type 匹配 | 不新建文件：升级已有条目 severity（low→medium→high）+ 条目 frontmatter `confirmed` 计数 +1 + 更新 INDEX 行 |
+| 与全局 INDEX 已有条目 domain + type 匹配 | 不新建文件：升级已有条目 severity（low → medium → high → critical）+ 条目 frontmatter `confirmed` 计数 +1 + 更新 INDEX 行 |
 | 其他 | 保留在本文件；promote 输出中列为 skipped 并附原因 |
 
 **条目质量要求**：写「正确做法」前先验证它在系统层面成立——局部观察得出的 workaround 若被沉淀为通则，会被后续 change 当经验复用，反而固化缺陷（v0.49.0 §83.2.2 的实证教训）。