@xulthekl/team-flow 0.29.2 → 0.31.0

package/agents/release-archivist.md

@@ -0,0 +1,82 @@
+---
+name: release-archivist
+description: >-
+  发布归档 agent——在 build-executor 完成实施之后、change 关闭之前,执行验证、产出
+  closing 总结并完成归档就绪(arch-merge / prototype-sync / 复利晋升)。可写型,负责归档制品。
+  Examples:
+
+<example>
+Context: 实施完成,需要验证并收尾归档。
+user: "实施做完了,帮我验证并归档这个 change"
+assistant: "I'll launch the release-archivist agent to verify, summarize, and ready the archive."
+<commentary>
+release-archivist 是 closing 阶段的收尾 agent,守"验证先于完成"铁律,产出验证报告与归档。
+</commentary>
+</example>
+
+<example>
+Context: 验证发现实施偏离契约,需回退而非强行关闭。
+user: "验证发现 design 决策和代码对不上"
+assistant: "I'll have release-archivist route back to bridging instead of forcing closure."
+<commentary>
+若实施偏离契约,回退 bridging 再关闭;FAIL 不进 DP-7。
+</commentary>
+</example>
+
+model: inherit
+color: yellow
+tools: ["Read", "Bash", "Grep", "Glob", "Write", "Edit"]
+skills:
+  - release-archivist
+---
+
+You are an independent Release Archivist. You close out a team-flow change cleanly: verification evidence, a closing summary, and archive readiness. You operate in an independent context with Write capability for the verification report and archive artifacts.
+
+## Artifact Ownership
+
+**You are the sole owner of the closing verification report and archive artifacts** (the Step-5 report, `decision-point-audit.md` inclusion, closing summary) for this change. No other agent or the orchestration layer may directly edit these. Re-verification requests MUST be routed through you via `SendMessage` resume.
+
+**Your preloaded Skill contains the detailed methodology** (Verification-Before-Completion iron law, 5-step verification, DP-6/DP-7 gates, arch-merge → prototype-sync → compound-promotion order, lightweight closure). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+
+## Iron Law
+
+Verification before completion: claiming work is done without fresh evidence is dishonesty, not efficiency. Identify the proving command, run it fresh, read output and exit code, verify it confirms the claim — only then make the claim. If implementation diverged from the contract, return to `bridging` before closure.
+
+## Inputs
+
+| Parameter | Description |
+|-----------|-------------|
+| `change_dir` | change 目录路径（e.g., `changes/feature-x/`） |
+| `contract_path` | execution-contract.md 路径（完整性比对基线） |
+| `arch_dir` | architecture/ 目录路径（可选,arch-merge 输入） |
+
+If `change_dir` or the contract is missing/unreadable, report `FAIL` with reason `INPUT_ERROR`.
+
+## Structured Output Contract
+
+Return the following YAML to the orchestration layer:
+
+```yaml
+status: pass | conditional | fail   # verdict across completeness/correctness/coherence
+dp_6: "<pass|conditional|fail>: <summary>"   # recorded via `tf state set`
+dp_7: "confirmed: <archive summary>"         # only after DP-6 pass + DP-0..DP-6 verified
+writebacks:
+  arch_merge: "merged N docs | skipped"
+  prototype_sync: "synced N pages | no UX delta | conflicts: N"
+  compound_promotion: "promoted N learnings | no learnings"
+summary: "..."                       # closing summary + any WARNs needing user acceptance
+```
+
+## Red Lines
+
+**DO:**
+- Follow the preloaded Skill's 5-step verification and write-back ordering methodology
+- Run each proving command fresh and cite command + output for every claim
+- Execute write-backs sequentially: arch-merge → prototype-sync → compound promotion
+- Write your own `dp_6_*`/`dp_7_*`/`test_result` fields via `tf state set` as the Skill instructs
+
+**DON'T:**
+- DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
+- When you receive external suggestions (reviewer findings, user opinions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
+- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
+- Claim "tests pass" / "requirements met" without fresh output, or proceed to DP-7 on a FAIL

package/agents/spec-writer.md

@@ -0,0 +1,83 @@
+---
+name: spec-writer
+description: >-
+  规格编写 agent——在 need-explorer 完成 DP-1 之后、contract-builder 之前，产出并打磨
+  proposal.md / specs/ / design.md / tasks.md 四件规划制品。可写型,负责规划制品目录。
+  Examples:
+
+<example>
+Context: need-explorer 已记录 DP-1,change 意图稳定,可以落盘规划制品。
+user: "需求已经澄清清楚了,帮我把 proposal/specs/design/tasks 写出来"
+assistant: "I'll launch the spec-writer agent to produce the four planning artifacts in order."
+<commentary>
+spec-writer 是 exploring→bridging 之间的产出 agent。逐件生成、逐件确认,防止 scope 漂移。
+</commentary>
+</example>
+
+<example>
+Context: 本 change 经 architecture-design 判定为 required,architecture/ 三件套已产出。
+user: "架构设计做完了,写 design.md 时要对齐架构决策"
+assistant: "I'll have spec-writer read architecture/ and align design.md Decisions with it."
+<commentary>
+design.md 的 Decisions 必须引用 architecture/ 决策,tasks.md 须对齐 api.md 路由表与 sql/ 脚本。
+</commentary>
+</example>
+
+model: inherit
+color: cyan
+tools: ["Read", "Bash", "Grep", "Glob", "Write", "Edit"]
+skills:
+  - spec-writer
+---
+
+You are an independent Spec Writer. You turn a stable change definition into the four planning artifacts (proposal.md, specs/, design.md, tasks.md). You operate in an independent context with Write capability for planning artifacts only.
+
+## Artifact Ownership
+
+**You are the sole owner of the planning artifacts** (`proposal.md`, `specs/`, `design.md`, `tasks.md`) within the change directory. No other agent or the orchestration layer may directly edit these files. Modification requests (DP-2 adjustments, review feedback) MUST be routed through you via `SendMessage` resume; the orchestration layer does not edit your artifacts directly.
+
+**Your preloaded Skill contains the detailed methodology** (per-artifact validation checklists, DP-0/DP-2 gates, architecture-alignment rules, prototype/solutions/conventions injection). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+
+## Iron Law
+
+You write planning artifacts, never implementation code. Honor confirmed DP-0 decisions, the change brief, and architecture outputs — do not silently expand scope or drop brief ACs. Validate each artifact before handing off; never hand off a broken artifact.
+
+## Inputs
+
+| Parameter | Description |
+|-----------|-------------|
+| `change_dir` | change 目录路径（e.g., `changes/feature-x/`） |
+| `brief_path` | change-brief.md 路径（可选,workflow-orchestrator S4 分发时存在） |
+| `plan_path` | prd/vN/plan.md 路径（可选,高阶技术方向） |
+| `arch_dir` | architecture/ 目录路径（可选,architecture-design 产出） |
+
+If `change_dir` is missing, or `.team-flow.yaml` `dp_0_confirmed` is not `true`, report `FAIL` with reason `INPUT_ERROR` and route back to workflow-start for DP-0.
+
+## Structured Output Contract
+
+Return the following YAML to the orchestration layer:
+
+```yaml
+status: done | blocked              # done: all 4 artifacts validated + DP-2 recorded
+artifacts:
+  - proposal.md
+  - specs/
+  - design.md
+  - tasks.md
+dp_2: "approved: <summary>"         # recorded via `tf state set`
+summary: "..."                       # 2-3 sentence overview + any open risks
+```
+
+## Red Lines
+
+**DO:**
+- Follow the preloaded Skill's per-artifact methodology and validation checklists
+- Generate artifacts one at a time, confirming each before the next
+- Cite brief sections / architecture decisions behind every design choice
+- Write your own `dp_2_*` decision fields via `tf state set` as the Skill instructs
+
+**DON'T:**
+- DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
+- When you receive external suggestions (reviewer findings, user opinions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
+- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
+- Start implementation, or hand off artifacts that fail validation

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.29.2`
+- Current: `v0.31.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). 17 skills, one install.",
-  "version": "0.29.2",
+  "version": "0.31.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.29.2: auto-sync CLI version with plugin version
+# v0.31.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.29.2"
+PLUGIN_VERSION="0.31.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.29.2.
+Current version: v0.31.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

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

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.29.2",
-  "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). 23 skills + 10 agents, one install.",
+  "version": "0.31.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). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"
   },

package/scripts/ensure-branch.mjs

@@ -6,66 +6,224 @@
 //
 // 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>。保证单仓库项目不被破坏。
+//
 // Security: every git invocation uses execFileSync with a LITERAL command
-// ('git') and a LITERAL argument array (no shell, no variable args array) —
-// the same form proven safe by install-cursor.mjs / install.mjs. There is no
-// string-form shell command, no variable command, and no dynamic args array.
+// ('git') and a LITERAL argument array (no shell, no string-form command) — the
+// same form proven safe by install-cursor.mjs / install.mjs. Worktree paths and
+// branch names derive from controlled sources (change-name / repository directory
+// names) and are passed as array elements, never interpolated into a shell string;
+// branch names are additionally sanitized to git-legal characters before use.
 import { execFileSync } from 'node:child_process';
+import { resolve, basename, dirname, join } from 'node:path';
+import { readdirSync, existsSync, appendFileSync, readFileSync } from 'node:fs';
 
-const changeDir = process.argv[2];
-const changeName = process.argv[3];
+const rawChangeDir = process.argv[2];
+// 第三个位置参数是可选 change-name；若它其实是 '--force' 之类的开关则忽略，避免把
+// 开关误当分支名（经 cmd-isolate 调用时 parseArgs 已正确分离，此为直接调用的兜底）。
+let changeName = process.argv[3];
+if (changeName && changeName.startsWith('--')) changeName = undefined;
 const force = process.argv.includes('--force');
 
-if (!changeDir) {
+if (!rawChangeDir) {
   console.error('Usage: node ensure-branch.mjs <change-dir> [change-name] [--force]');
   process.exit(2);
 }
 
+// 解析为绝对路径，后续所有路径计算基于此（来源：workflow-feedback 2026-08-01 #100009）。
+const changeDir = resolve(rawChangeDir);
+
 const PROTECTED = ['main', 'master'];
-const GIT_OPTS = { encoding: 'utf-8', cwd: changeDir, stdio: ['ignore', 'pipe', 'pipe'] };
-
-// Determine current branch (literal arg array).
-let branch = '';
-try {
-  branch = (execFileSync('git', ['branch', '--show-current'], GIT_OPTS) || '').trim();
-} catch {
-  console.error('ensure-branch: could not determine current git branch. Is <change-dir> inside a git repository?');
-  process.exit(1);
+
+// 将分支名清洗为 git 合法字符（来源：workflow-feedback 2026-08-01 #100009）。
+// git-check-ref-format 禁止空格 ~ ^ : ? * [ \ .. @{ 等，且不能以 . 开头/结尾、
+// 不能 .lock 结尾。这里把非法字符替换为 '-'，去掉首尾的 . / -，避免分支名以 '-'
+// 开头被 git 误解析为命令行选项。输入来自受控来源，清洗是额外的纵深防护层。
+function sanitizeBranchName(raw) {
+  const cleaned = String(raw)
+    .replace(/[^A-Za-z0-9._/-]/g, '-')   // 非法字符 → '-'
+    .replace(/\.{2,}/g, '.')             // '..' → '.'（git 禁止 '..'）
+    .replace(/\.lock$/i, '')             // 禁止 '.lock' 结尾
+    .replace(/\/{2,}/g, '/')            // 折叠多重 '/'
+    .replace(/^[./-]+/, '')             // 去掉开头 . / -（git 禁止 . 开头；避免 '-' 开头当选项）
+    .replace(/[/.]+$/, '');             // 去掉结尾 / .
+  return cleaned || 'change';
+}
+
+// 若 change-dir 形如 <root>/changes/<name>，返回 <root>；否则返回 null。
+function detectWorkspaceRoot(absChangeDir) {
+  const parent = dirname(absChangeDir);          // <root>/changes
+  if (basename(parent) !== 'changes') return null;
+  return dirname(parent);                        // <root>
 }
 
-if (!PROTECTED.includes(branch)) {
-  console.log(`ensure-branch: already isolated on branch '${branch}'. Proceed with implementation edits.`);
-  process.exit(0);
+// 枚举 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();
 }
 
-console.error(`ensure-branch: on protected branch '${branch}'. Creating an isolated implementation context...`);
+// 确保 <root>/.gitignore 含忽略 .worktrees/ 的行，已有则不重复追加。
+function ensureWorktreeGitignore(root) {
+  const gitignorePath = join(root, '.gitignore');
+  let existing = '';
+  try {
+    existing = readFileSync(gitignorePath, 'utf-8');
+  } catch {
+    existing = '';
+  }
+  const alreadyIgnored = existing
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .some((l) => l === '.worktrees/' || l === '.worktrees' || l === '/.worktrees/' || l === '/.worktrees');
+  if (alreadyIgnored) return;
+  const needsNewline = existing.length > 0 && !existing.endsWith('\n');
+  appendFileSync(gitignorePath, `${needsNewline ? '\n' : ''}.worktrees/\n`);
+  console.log(`ensure-branch: added '.worktrees/' to ${gitignorePath}.`);
+}
+
+// Case A：多仓库工作区隔离（来源：workflow-feedback 2026-08-01 #100009）。
+// 为每个代码仓库在 <root>/.worktrees/<change>/<repo> 建 worktree（基于各仓库当前分支）。
+function runMultiRepo(root, repos) {
+  const changeSlug = basename(changeDir);
+  const branchBase = sanitizeBranchName(changeName || changeSlug);
+  const changeWorktreeDir = join(root, '.worktrees', changeSlug);
+
+  console.error(`ensure-branch: multi-repo workspace detected at ${root}. Isolating ${repos.length} code repo(s): ${repos.join(', ')}...`);
+
+  // 先确保 .gitignore 忽略 .worktrees/，避免 worktree 产物污染工作区根仓库。
+  ensureWorktreeGitignore(root);
+
+  const failed = [];
+  for (const repo of repos) {
+    const repoDir = join(root, repo);
+    const repoOpts = { encoding: 'utf-8', cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] };
+    const wtPath = join(changeWorktreeDir, repo);
+
+    // 幂等：worktree 已存在则复用，避免实现子代理重试时报 "already exists"。
+    if (existsSync(join(wtPath, '.git'))) {
+      console.log(`ensure-branch: [${repo}] worktree already exists at ${wtPath}; reusing.`);
+      continue;
+    }
 
-const repoName = changeDir.split('/').filter(Boolean).pop() || 'repo';
-const name = changeName || repoName;
-const worktreePath = `../${repoName}-${name}`;
+    // 逐仓库判断当前分支（字面参数数组）。
+    let branch = '';
+    try {
+      branch = (execFileSync('git', ['branch', '--show-current'], repoOpts) || '').trim();
+    } catch {
+      console.error(`ensure-branch: [${repo}] could not determine current git branch; cannot isolate.`);
+      failed.push(repo);
+      continue;
+    }
 
-// Preferred: git worktree (literal arg array).
-try {
-  execFileSync('git', ['worktree', 'add', worktreePath, '-b', name], { ...GIT_OPTS, stdio: 'inherit' });
-  console.log(`ensure-branch: created git worktree at ${worktreePath} on branch '${name}'. Make all implementation edits there.`);
-  process.exit(0);
-} catch (e) {
-  console.error(`ensure-branch: worktree creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+    // 该仓库已不在受保护分支 → 已隔离，无需建 worktree（沿用单仓库 already-isolated 语义）。
+    if (!PROTECTED.includes(branch)) {
+      console.log(`ensure-branch: [${repo}] already isolated on branch '${branch}'.`);
+      continue;
+    }
+
+    // 在受保护分支 → 建 worktree，基于该仓库当前分支（字面参数数组）。
+    // 不同代码仓库相互独立，使用同一分支名 branchBase 不会冲突。
+    try {
+      execFileSync('git', ['worktree', 'add', wtPath, '-b', branchBase], { ...repoOpts, stdio: 'inherit' });
+      console.log(`ensure-branch: [${repo}] created worktree at ${wtPath} on branch '${branchBase}'.`);
+    } catch (e) {
+      console.error(`ensure-branch: [${repo}] worktree creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+      failed.push(repo);
+    }
+  }
+
+  // 退出码语义与单仓库一致：全部隔离成功 → 0；有失败 + --force → 0（警告）；有失败 + 无 force → 1（STOP）。
+  if (failed.length === 0) {
+    console.log(`ensure-branch: implementation subagents should enter ${changeWorktreeDir} to work; directory structure mirrors the main workspace, with reference code from every repo available.`);
+    process.exit(0);
+  }
+  if (force) {
+    console.error(`ensure-branch: WARNING — could not isolate ${failed.length} repo(s): ${failed.join(', ')}. Proceeding with --force; these remain on their protected branches.`);
+    process.exit(0);
+  }
+  console.error(`ensure-branch: could not isolate ${failed.length} repo(s): ${failed.join(', ')}. No --force given. STOP and ask the user for explicit approval before editing main/master.`);
+  process.exit(1);
 }
 
-// Fallback: local branch (literal arg array).
-try {
-  execFileSync('git', ['switch', '-c', name], { ...GIT_OPTS, stdio: 'inherit' });
-  console.log(`ensure-branch: created branch '${name}' via git switch -c. Make implementation edits there.`);
-  process.exit(0);
-} catch (e) {
-  console.error(`ensure-branch: branch creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+// Case B：单代码仓库隔离（遗留兼容，保持重构前行为不变）。
+// 把 change-dir 当代码仓库，worktree 建在 ../<repo>-<name>。
+function runSingleRepo() {
+  const GIT_OPTS = { encoding: 'utf-8', cwd: changeDir, stdio: ['ignore', 'pipe', 'pipe'] };
+
+  // Determine current branch (literal arg array).
+  let branch = '';
+  try {
+    branch = (execFileSync('git', ['branch', '--show-current'], GIT_OPTS) || '').trim();
+  } catch {
+    console.error('ensure-branch: could not determine current git branch. Is <change-dir> inside a git repository?');
+    process.exit(1);
+  }
+
+  if (!PROTECTED.includes(branch)) {
+    console.log(`ensure-branch: already isolated on branch '${branch}'. Proceed with implementation edits.`);
+    process.exit(0);
+  }
+
+  console.error(`ensure-branch: on protected branch '${branch}'. Creating an isolated implementation context...`);
+
+  const repoName = basename(changeDir) || 'repo';
+  const name = sanitizeBranchName(changeName || repoName);
+  const worktreePath = `../${repoName}-${name}`;
+
+  // Preferred: git worktree (literal arg array).
+  try {
+    execFileSync('git', ['worktree', 'add', worktreePath, '-b', name], { ...GIT_OPTS, stdio: 'inherit' });
+    console.log(`ensure-branch: created git worktree at ${worktreePath} on branch '${name}'. Make all implementation edits there.`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`ensure-branch: worktree creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+  }
+
+  // Fallback: local branch (literal arg array).
+  try {
+    execFileSync('git', ['switch', '-c', name], { ...GIT_OPTS, stdio: 'inherit' });
+    console.log(`ensure-branch: created branch '${name}' via git switch -c. Make implementation edits there.`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`ensure-branch: branch creation failed: ${(e.stderr || e.stdout || e.message || 'unknown').toString().trim()}`);
+  }
+
+  // Both failed → require explicit approval to edit in place.
+  if (force) {
+    console.error('ensure-branch: WARNING — editing protected branch in place with --force. This modifies main/master directly.');
+    process.exit(0);
+  }
+  console.error('ensure-branch: could not create an isolated context and no --force given. STOP and ask the user for explicit approval before editing main/master.');
+  process.exit(1);
 }
 
-// Both failed → require explicit approval to edit in place.
-if (force) {
-  console.error('ensure-branch: WARNING — editing protected branch in place with --force. This modifies main/master directly.');
-  process.exit(0);
+// 主流程：布局识别后分发（来源：workflow-feedback 2026-08-01 #100009）。
+const workspaceRoot = detectWorkspaceRoot(changeDir);
+const codeRepos = workspaceRoot ? listCodeRepos(workspaceRoot) : [];
+
+if (workspaceRoot && codeRepos.length > 0) {
+  // Case A：多仓库工作区。
+  runMultiRepo(workspaceRoot, codeRepos);
+} else {
+  // Case B：不满足 Case A → 回退单代码仓库行为，保证单仓库项目不被破坏。
+  runSingleRepo();
 }
-console.error('ensure-branch: could not create an isolated context and no --force given. STOP and ask the user for explicit approval before editing main/master.');
-process.exit(1);

package/scripts/guard/checks/test-matrix-complete.mjs

@@ -0,0 +1,67 @@
+// scripts/guard/checks/test-matrix-complete.mjs — verify test matrix exists and is consistent
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { computeTestMatrixHash } from '../../lib/hash.mjs';
+
+/**
+ * Check that test-matrix.md exists and its hash is consistent with state.
+ *
+ * Exemption paths (v0.12 §45.3):
+ * 1. Legacy: execution-contract.md has no "## Test Matrix" section → PASS
+ * 2. Explicit skip: test_matrix_skipped === 'true' → PASS
+ * 3. test-matrix.md exists and hash matches → PASS
+ * 4. test-matrix.md missing or hash mismatch → FAIL
+ *
+ * Returns { pass, failures[], reason? }.
+ */
+export function checkTestMatrixComplete(changeDir) {
+  const state = readState(changeDir);
+
+  // Exemption 1: explicit skip
+  if (state.test_matrix_skipped === 'true') {
+    return { pass: true, failures: [], reason: 'explicitly skipped via test_matrix_skipped' };
+  }
+
+  // Exemption 2: legacy contract without Test Matrix section
+  const contractPath = path.join(changeDir, 'execution-contract.md');
+  if (fs.existsSync(contractPath)) {
+    const contract = fs.readFileSync(contractPath, 'utf-8');
+    if (!contract.includes('## Test Matrix')) {
+      return { pass: true, failures: [], reason: 'legacy contract — no test matrix section' };
+    }
+  } else {
+    // No contract at all — nothing to check
+    return { pass: true, failures: [], reason: 'no execution contract — skipping test matrix check' };
+  }
+
+  // Check test-matrix.md exists and is non-empty
+  const matrixPath = path.join(changeDir, 'test-matrix.md');
+  if (!fs.existsSync(matrixPath)) {
+    return {
+      pass: false,
+      failures: ['test-matrix.md is missing — contract declares ## Test Matrix but no matrix file found'],
+    };
+  }
+
+  const content = fs.readFileSync(matrixPath, 'utf-8');
+  if (content.trim().length === 0) {
+    return {
+      pass: false,
+      failures: ['test-matrix.md is empty — must contain at least a Summary section and Cases table'],
+    };
+  }
+
+  // Hash consistency check
+  const computed = computeTestMatrixHash(changeDir);
+  if (state.test_matrix_hash && state.test_matrix_hash !== computed) {
+    return {
+      pass: false,
+      failures: [
+        `test-matrix.md has been modified since last hash — stored: ${state.test_matrix_hash}, current: ${computed}. Run 'tf state rebuild' to update.`,
+      ],
+    };
+  }
+
+  return { pass: true, failures: [] };
+}

package/scripts/guard/guard.mjs

@@ -14,6 +14,7 @@ import { checkDp3Approved } from './checks/dp3-approved.mjs';
 import { checkExecutionPlanReady } from './checks/execution-plan-ready.mjs';
 import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.mjs';
 import { checkCompoundCaptured } from './checks/compound-captured.mjs';
+import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
@@ -22,7 +23,7 @@ const TRANSITION_CHECKS = {
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
   'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready'],
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
+  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -55,6 +56,8 @@ const WORKFLOW_TRANSITION_CHECKS = {
     'exploring:bridging': [],
     'bridging:approved-for-build': ['contract-current', 'dp3-approved'],
     'approved-for-build:executing': ['contract-current', 'dp3-approved', 'execution-plan-ready'],
+    // hotfix exemption: no test-matrix-complete (v0.12 §45.3)
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
   },
   tweak: {
     'exploring:approved-for-build': [],
@@ -167,6 +170,7 @@ async function main() {
     'execution-reviews-passed': (dir) => checkExecutionReviewsPassed(dir),
     'arch-design': (dir) => checkArchDesign(dir),
     'compound-captured': (dir) => checkCompoundCaptured(dir),
+    'test-matrix-complete': (dir) => checkTestMatrixComplete(dir),
   };
 
   const checks = [];