@xulthekl/team-flow 0.29.1 → 0.30.0

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.1`
+- Current: `v0.30.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.1",
+  "version": "0.30.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.29.1: auto-sync CLI version with plugin version
+# v0.30.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.29.1"
+PLUGIN_VERSION="0.29.2"
 
 # ═══════════════════════════════════════════════════════════════
 # 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.1.
+Current version: v0.30.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.1",
-  "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.30.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.1",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 10 agents, one install.",
+  "version": "0.30.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). 23 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/lib/cmd-doctor.mjs

@@ -3,6 +3,8 @@ import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 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';
 
 const RUNTIME_SKILLS = new Set([
   'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
@@ -220,6 +222,42 @@ function checkDocs(root) {
   return { pass: false, message: warnings.join('; ') };
 }
 
+// 非法 state 巡检(来源:workflow-feedback 2026-08-01,#100004):
+// 扫描 changes/<name>/.team-flow.yaml,若 state 字段不在 VALID_STATES 则报 FAIL。
+// 非法值通常由子代理绕过 CLI 直接 Edit .team-flow.yaml 导致,提示修复为合法值。
+// 沿用 checkSkills 的目录扫描 + 计数报告风格。
+function checkChangeStates(root) {
+  const changesDir = join(root, 'changes');
+  if (!existsSync(changesDir)) {
+    return { pass: true, message: 'no changes/ directory (skipped)' };
+  }
+  const dirs = readdirSync(changesDir).filter(f => {
+    try { return statSync(join(changesDir, f)).isDirectory(); } catch { return false; }
+  });
+  const invalid = [];
+  let checked = 0;
+  for (const d of dirs) {
+    if (!existsSync(join(changesDir, d, '.team-flow.yaml'))) continue;
+    checked += 1;
+    const current = readState(join(changesDir, d)).state;
+    if (!VALID_STATES.includes(current)) {
+      invalid.push(`${d}='${current}'`);
+    }
+  }
+  if (checked === 0) {
+    return { pass: true, message: 'no state files under changes/ (skipped)' };
+  }
+  if (invalid.length > 0) {
+    return {
+      pass: false,
+      message:
+        `state 值非法(可能是子代理绕过 CLI 直接 Edit .team-flow.yaml 所致):${invalid.join('; ')}。` +
+        `请修复为合法值:${VALID_STATES.join('/')}`,
+    };
+  }
+  return { pass: true, message: `${checked} change(s) have legal state values` };
+}
+
 export async function run(args) {
   const root = process.cwd();
   const config = loadConfig(root);
@@ -236,6 +274,7 @@ export async function run(args) {
     ['dist/', checkDist(root)],
     ['Node.js', checkNodeVersion()],
     ['Docs', checkDocs(root)],
+    ['Change states', checkChangeStates(root)],
   ];
 
   // Config check
@@ -264,4 +303,4 @@ export async function run(args) {
   }
 }
 
-export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs };
+export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs, checkChangeStates };

package/scripts/lib/cmd-state.mjs

@@ -2,18 +2,15 @@
 import { parseArgs } from 'node:util';
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import path, { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readState, writeState, updateField, rebuildState } from './state-loader.mjs';
+// VALID_STATES 统一从 state-loader.mjs 引入(状态机合法值唯一真相源),不再本地硬编码。
+// 来源:workflow-feedback 2026-08-01,#100005。
+import { readState, writeState, updateField, rebuildState, VALID_STATES } from './state-loader.mjs';
 import { computeArtifactsHash, computeContractHash } from './hash.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const VALID_STATES = [
-  'exploring', 'specifying', 'bridging', 'approved-for-build',
-  'executing', 'debugging', 'closing', 'abandoned',
-];
-
 const SETTABLE_FIELDS = [
   'workflow', 'test_result', 'batches_completed', 'spec_merged',
   'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
@@ -44,7 +41,7 @@ export async function run(args) {
   });
 
   const sub = positionals[0];  // init | check | transition | get | rebuild | set
-  const changeDir = positionals[1];
+  let changeDir = positionals[1];
   const arg = positionals[2];  // <to-state> for transition, <field> for get
 
   if (!changeDir) {
@@ -53,6 +50,13 @@ export async function run(args) {
     process.exit(2);
   }
 
+  // 修复相对路径 bug(来源:workflow-feedback 2026-08-01,#100005)。
+  // 根因:readState 用 path.join(changeDir,...) 按用户 cwd 解析,而 transition 分支 spawn guard
+  // 子进程时 cwd 设为包根(join(__dirname,'..','..'))+ 原样 changeDir,两处基准不一致——用户传
+  // 相对路径时 guard 在包根下找不到产物。统一在入口 resolve 为绝对路径,使后续 readState /
+  // guard spawn / existsSync 全部基于同一绝对基准,消除 cwd 歧义。
+  changeDir = path.resolve(changeDir);
+
   // Unknown subcommand: report a usage error (exit 2) BEFORE the BUG-B
   // state-file existence check, so a bad subcommand is not masked by the
   // "No state file" error (which would return exit 1 instead of exit 2).
@@ -222,7 +226,18 @@ export async function run(args) {
         process.exit(2);
       }
       if (!SETTABLE_FIELDS.includes(field)) {
-        console.error(`⛔ Field '${field}' is not settable (use 'transition' for state, or check SETTABLE_FIELDS)`);
+        // 错误提示升级(来源:workflow-feedback 2026-08-01,#100005):
+        // 'state' 是最常被误用 set 的字段,专门给出完整 transition 语法示例;合法状态清单
+        // 引用 VALID_STATES(唯一真相源),不硬编码。保留 'not settable' 措辞以兼容既有回归测试。
+        if (field === 'state') {
+          console.error(
+            `⛔ 'state' 不是可 set 的字段(not settable)。状态转换请用完整语法:\n` +
+            `   tf state transition <change-dir 绝对路径> <目标状态>\n` +
+            `   合法状态:${VALID_STATES.join('/')}`
+          );
+        } else {
+          console.error(`⛔ Field '${field}' is not settable (use 'transition' for state, or check SETTABLE_FIELDS)`);
+        }
         process.exit(1);
       }
       updateField(changeDir, field, value);

package/scripts/lib/state-loader.mjs

@@ -4,6 +4,14 @@ import path from 'node:path';
 
 const STATE_FILE = '.team-flow.yaml';
 
+// 状态机合法值唯一真相源 (来源:workflow-feedback 2026-08-01,#100005)。
+// 所有状态枚举校验统一引用此常量,禁止在各处硬编码状态字符串数组,避免多处定义漂移。
+// cmd-state.mjs(transition 校验 / set 报错)、cmd-doctor.mjs(非法 state 巡检)均从这里 import。
+export const VALID_STATES = [
+  'exploring', 'specifying', 'bridging', 'approved-for-build',
+  'executing', 'debugging', 'closing', 'abandoned',
+];
+
 const BUILTIN_DEFAULTS = {
   state: 'exploring',
   workflow: 'auto',
@@ -74,6 +82,20 @@ export function readState(changeDir) {
  * Write state object to .team-flow.yaml.
  */
 export function writeState(changeDir, state) {
+  // Defense-in-depth 状态合法性校验 (来源:workflow-feedback 2026-08-01,#100004)。
+  // 主修复是子代理 prompt 禁令(禁止绕过 CLI 直接 Edit .team-flow.yaml);此处是最后一道防线,
+  // 拦截任何非法 state 落盘。init/transition/rebuild/updateField 等 CLI 路径产生的 state 均合法
+  // (缺失时回退 'exploring'),不会误伤;仅当出现非法值时抛错,提示用 tf doctor 排查。
+  const effectiveState = state.state || 'exploring';
+  if (!VALID_STATES.includes(effectiveState)) {
+    throw new Error(
+      `Refusing to write illegal state '${effectiveState}' to ${path.join(changeDir, STATE_FILE)}. ` +
+      `Legal states: ${VALID_STATES.join(', ')}. ` +
+      `This is usually caused by a subagent bypassing the CLI and editing .team-flow.yaml directly — ` +
+      `restore a legal value or run 'tf doctor' to diagnose.`
+    );
+  }
+
   const filePath = path.join(changeDir, STATE_FILE);
   const lines = [];
   lines.push('# .team-flow.yaml — lightweight state machine');

package/skills/build-executor/SKILL.md

@@ -27,17 +27,27 @@ Branch/worktree preflight before ANY implementation edit (mandatory — do not s
    ```bash
    tf isolate <change-dir>
    ```
-   This script enforces git isolation: if you are on `main`/`master` it creates a
-   git worktree (preferred) or a new branch, and exits non-zero if it cannot and you
-   have not approved `--force`.
+   This script enforces git isolation. In a **multi-repo workspace** (a workspace root
+   whose direct subdirectories are independent code repositories, e.g. `bff-*`/`ui-*`/
+   `prototype/`, while the root itself is often a near-empty git repo), it creates one git
+   worktree per code repo under `<workspace>/.worktrees/<change>/<repo>` — each based on
+   that repo's current branch — so the implementation subagent enters that aggregated
+   directory and sees reference code from every repo with the same layout as the main
+   workspace. In a **single code repository** it falls back to creating one git worktree
+   (preferred) or a new branch. It exits non-zero if it cannot isolate and you have not
+   approved `--force`.
 2. If `tf isolate` exits non-zero: STOP. Do not edit `main`/`master` in place.
    Ask the user for explicit approval (and re-run with `tf isolate <change-dir> --force`
    only after they approve).
-3. If it succeeds, report the chosen branch/worktree and make all implementation
+3. If it succeeds, report the chosen branch/worktree — in a multi-repo workspace, the
+   aggregated `<workspace>/.worktrees/<change>/` directory — and make all implementation
    edits there.
 
 ## Core Laws
 
+### Law 0: State Field Boundary (v0.30.0)
+本 skill 仅通过 `tf state set` 写自己的 `dp_5_*` 决策字段；**MUST NOT** 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段——状态转换是主代理（workflow-start）经 `tf state transition` 的专有职责（来源：workflow-feedback 2026-08-01）。
+
 ### Law 1: Contract First
 The execution contract is the approved handoff artifact, not chat history.
 

package/skills/contract-builder/SKILL.md

@@ -53,6 +53,8 @@ Generate minimal contract: Intent Lock (one sentence), Task List (numbered), App
 
 ## Guardrails
 
+- **状态字段禁写（v0.30.0）**：仅写本 skill 的 `dp_3_*` 决策字段；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
+
 - Do not continue to implementation if ambiguity remains
 - Do not approve the contract on the user's behalf
 - Do not skip the contract because planning docs look complete

package/skills/need-explorer/SKILL.md

@@ -52,6 +52,8 @@ Once DP-1 is recorded, hand off to `spec-writer`.
 
 ## Anti-Patterns
 
+- **修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段**（v0.30.0 禁止）：状态转换是主代理经 `tf state transition` 的专有职责；need-explorer 只写自己的 `dp_1_*` 决策字段（来源：workflow-feedback 2026-08-01）。
+
 - **Skipping exploration**: "Simple" changes have scope too. Five minutes of exploration prevents two hours of rework.
 - **Proposing solutions before clarifying**: If the user says "add caching," first ask what problem caching solves.
 - **Exploring indefinitely**: Stop when change name, problem statement, scope, non-goals, success criteria, and decomposition decision are all clear.