@xulthekl/team-flow 0.42.0 → 0.44.0

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.42.0.
+Current version: v0.44.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.42.0",
-  "description": "Unified plugin (24 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.",
+  "version": "0.44.0",
+  "description": "Unified plugin (25 skills + 16 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",
   "bin": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.42.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.",
+  "version": "0.44.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). 25 skills + 16 agents, one install.",
   "author": {
     "name": "LT"
   },

package/scripts/lib/cmd-deisolate.mjs

@@ -26,6 +26,7 @@ export async function run(args) {
     options: {
       merge: { type: 'boolean', default: false },
       clean: { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false }, // v0.43.1：跳过 dirty 阻断
       'project-root': { type: 'string' },
       json: { type: 'boolean', default: false },
       help: { type: 'boolean', default: false },
@@ -69,6 +70,12 @@ export async function run(args) {
   } else {
     printReport(results, values);
   }
+
+  // v0.43.1：merge 失败（冲突 / dirty 阻断）→ exit 非零，调用方（release-archivist）可检测。
+  // nothing-to-merge（success + skipped）不算失败。
+  if (results.some(r => r.merge && r.merge.success === false)) {
+    process.exitCode = 1;
+  }
 }
 
 
@@ -163,9 +170,9 @@ function processRepo(repo, values) {
     result.dirty = '?';
   }
 
-  // 操作
+  // 操作（v0.43.1：合并前防护——dirty 阻断 / ahead==0 短路，设计增强方案 v0.18 §74）
   if (values.merge) {
-    result.merge = mergeBranch(repo, branch, masterBranch);
+    result.merge = doMerge(repo, branch, masterBranch, result, values);
   }
   if (values.clean) {
     result.clean = cleanWorktree(repo, branch);
@@ -194,6 +201,28 @@ function detectMasterBranch(repoPath) {
   return 'master';
 }
 
+// v0.43.1：合并前防护（设计增强方案 v0.18 §74）
+// 1. dirty 阻断：worktree 有未提交改动时默认不合并（避免改动混入 master），--force 跳过
+// 2. ahead==0 短路：分支相对目标分支无新 commit 时跳过合并（幂等，可安全重复调用）
+// 3. 冲突报告：merge 失败时解析 unmerged 文件列表，引导人工解决而非静默失败
+function doMerge(repo, branch, masterBranch, state, values) {
+  if (state.dirty === true && !values.force) {
+    return {
+      success: false,
+      skipped: 'dirty',
+      message: `Worktree has uncommitted changes — commit or stash them before merging, or use --force`,
+    };
+  }
+  if (typeof state.ahead === 'number' && state.ahead === 0) {
+    return {
+      success: true,
+      skipped: 'nothing-to-merge',
+      message: `Branch '${branch}' is up to date with '${masterBranch}' — nothing to merge`,
+    };
+  }
+  return mergeBranch(repo, branch, masterBranch);
+}
+
 function mergeBranch(repo, branch, masterBranch) {
   try {
     const output = execFileSync('git', ['merge', branch, '--no-edit'], {
@@ -201,7 +230,30 @@ function mergeBranch(repo, branch, masterBranch) {
     });
     return { success: true, message: output.trim() };
   } catch (e) {
-    return { success: false, message: (e.stderr || e.stdout || e.message || '').toString().trim() };
+    const raw = (e.stderr || e.stdout || e.message || '').toString().trim();
+    const conflicts = collectConflicts(repo.repoPath);
+    return {
+      success: false,
+      conflicts,
+      message: conflicts.length > 0
+        ? `Merge conflict in ${conflicts.length} file(s): ${conflicts.join(', ')}. Resolve manually, then 'git add' + 'git commit' to complete the merge.`
+        : raw,
+    };
+  }
+}
+
+// v0.43.1：解析 merge 冲突的 unmerged 文件列表（git status --porcelain 的 UU/AA/DD/AU/UA/DU/UD）
+function collectConflicts(repoPath) {
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf-8', cwd: repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return status
+      .split('\n')
+      .filter(line => /^(UU|AA|DD|AU|UA|DU|UD)/.test(line.trim()))
+      .map(line => line.trim().replace(/^(UU|AA|DD|AU|UA|DU|UD)\s+/, ''));
+  } catch {
+    return [];
   }
 }
 
@@ -260,7 +312,18 @@ function printReport(results, values) {
     console.log(`    Uncommitted changes: ${r.dirty === true ? '⚠️  YES' : r.dirty === false ? 'no' : 'unknown'}`);
 
     if (r.merge) {
-      console.log(`    Merge: ${r.merge.success ? '✅ ' + r.merge.message : '❌ ' + r.merge.message}`);
+      if (r.merge.skipped === 'nothing-to-merge') {
+        console.log(`    Merge: ⏭️  ${r.merge.message}`);
+      } else if (r.merge.skipped === 'dirty') {
+        console.log(`    Merge: ⛔ ${r.merge.message}`);
+      } else if (r.merge.success) {
+        console.log(`    Merge: ✅ ${r.merge.message}`);
+      } else {
+        console.log(`    Merge: ❌ ${r.merge.message}`);
+        if (r.merge.conflicts && r.merge.conflicts.length > 0) {
+          console.log(`    Conflicts: ${r.merge.conflicts.length} file(s)`);
+        }
+      }
     }
     if (r.clean) {
       console.log(`    Worktree removed: ${r.clean.worktreeRemoved ? '✅' : '❌'}`);
@@ -282,6 +345,7 @@ function printHelp() {
   console.log(`Usage:
   tf deisolate <change-dir>                    # dry-run: show worktree status
   tf deisolate <change-dir> --merge             # merge worktree branch back to master
+  tf deisolate <change-dir> --merge --force     # merge even with uncommitted changes
   tf deisolate <change-dir> --merge --clean     # merge + remove worktree + delete branch
   tf deisolate <change-dir> --clean             # remove worktree only (no merge)
   tf deisolate <change-dir> --json              # JSON output`);

package/scripts/team-flow.mjs

@@ -101,7 +101,7 @@ Commands:
                         Upgrade inline/batch to SDD, or replan existing SDD waves, as a new revision
   execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail
                         Record one review receipt for a planned wave
-  deisolate <change-dir> [--merge] [--clean] [--json]
+  deisolate <change-dir> [--merge] [--force] [--clean] [--json]
                         Show worktree status / merge branch back / clean worktree
   runtime check-update  Run a portable update check for canonical skills
   runtime infer <dir>   Infer workflow mode without a plugin-root path

package/skills/architecture-design/SKILL.md

@@ -66,7 +66,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 ### 输入
 
 - `change-brief.md`（scope / AC / 技术方向）
-- `prd/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
+- `requirement/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
 - `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源
 - 全局 `docs/architecture/`（As-Is 实际态基线，已落地部分）
 - 现有 `specs/`（若有）
@@ -156,7 +156,7 @@ changes/<name>/
 - **不**重复 Swagger 管理的内容：请求/响应 schema、错误码定义、参数明细等由 Swagger/OpenAPI 规范承载
 - frontmatter 须声明 `api_contract_manager: swagger`，表明详细契约由 Swagger 工具链管理
 - sql/ 目录中的 DDL 和 migration 脚本为独立可执行 `.sql` 文件，不嵌入 markdown 文档
-- **PRD 功能清单 → API 端点映射表（v0.29.0 §37 新增）**：在 api.md 中增加独立章节，逐条对照 `prd/vN/prd.md` 功能清单（如 F001_P0_P1 ~ P0_PN），映射每个功能点到对应的 API 端点。对于涉及子实体（明细/子项）的功能，必须确保独立 CRUD 端点存在——仅查询端点不覆盖"新增/编辑"功能。此映射表供 architecture-reviewer A4 交叉验证使用
+- **PRD 功能清单 → API 端点映射表（v0.29.0 §37 新增）**：在 api.md 中增加独立章节，逐条对照 `requirement/vN/prd.md` 功能清单（如 F001_P0_P1 ~ P0_PN），映射每个功能点到对应的 API 端点。对于涉及子实体（明细/子项）的功能，必须确保独立 CRUD 端点存在——仅查询端点不覆盖"新增/编辑"功能。此映射表供 architecture-reviewer A4 交叉验证使用
 
 **下游消费**：
 - `architecture/architecture.md` → spec-writer：design.md Decisions 约束

package/skills/architecture-design/references/s3.5-product-architecture.md

@@ -6,8 +6,8 @@
 
 ## 输入
 
-- prd/vN/prd.md（frozen_downstream，功能清单 F001_P0 等）
-- prd/vN/plan.md（高阶技术设计段：模块边界/技术选型/数据流/关键聚合划分）
+- requirement/vN/prd.md（frozen_downstream，功能清单 F001_P0 等）
+- requirement/vN/plan.md（高阶技术设计段：模块边界/技术选型/数据流/关键聚合划分）
 - prototype/（S2 产物，页面结构）
 - docs/architecture/baseline.md（S1 注入）
 - docs/architecture/CONCEPTS.md（领域词汇）
@@ -87,7 +87,7 @@ ARCH 完成（评审 PASS 或 skip 已物化）后，**阻塞确认**（AskUserQ
 - 产品级评审门 verdict = PASS（或 skip 已物化）
 - orchestrator.yaml 中 ARCH 阶段状态 = completed（workflow_phase: architecture）
 - **未触发** arch-merge 全局覆盖写（预测态不进实际态，P1）
-- **架构基线打戳（v0.36.3）**：首轮项目（`arch_baseline` 缺失）评审 PASS 后执行 `tf arch init --mode reconstruction --baseline-ref prd/vN/`（旧项目逆向重建）或 `--mode design`（全新项目正向设计）——arch-readiness/arch-snapshot 门禁的豁免键在此建立，项目进入「已建档」正轨
+- **架构基线打戳（v0.36.3）**：首轮项目（`arch_baseline` 缺失）评审 PASS 后执行 `tf arch init --mode reconstruction --baseline-ref requirement/vN/`（旧项目逆向重建）或 `--mode design`（全新项目正向设计）——arch-readiness/arch-snapshot 门禁的豁免键在此建立，项目进入「已建档」正轨
 
 ## 常见陷阱
 

package/skills/architecture-design/templates/change-brief.md

@@ -1,7 +1,7 @@
 ---
 upstream_source: orchestrator | manual | null
 upstream_req_id: <req-id>
-upstream_plan_ref: prd/vN/plan.md
+upstream_plan_ref: requirement/vN/plan.md
 upstream_change_id: C2
 plan_hash: sha256:<plan.md 内容摘要>
 ---
@@ -25,5 +25,5 @@ plan_hash: sha256:<plan.md 内容摘要>
 
 ## PRD & plan 引用
 
-- PRD: prd/vN/prd.md §<相关章节>
-- Plan: prd/vN/plan.md ### <C-ID>
+- PRD: requirement/vN/prd.md §<相关章节>
+- Plan: requirement/vN/plan.md ### <C-ID>

package/skills/build-executor/SKILL.md

@@ -46,7 +46,7 @@ Branch/worktree preflight before ANY implementation edit (mandatory — do not s
 ### UI Contract Prototype Location (v0.37.0 §68.5)
 
 When implementing UI tasks, the UI contract source is the **prototype version worktree**, not the change worktree's prototype copy:
-- **定位**：读 `change-brief.md` 的 `upstream_plan_ref: prd/vN/plan.md`（或 change 目录名 `v{N}-` 前缀）→ PRD 版本 vN → 原型 worktree = `<workspace>/.worktrees/prd-vN/prototype/`
+- **定位**：读 `change-brief.md` 的 `upstream_plan_ref: requirement/vN/plan.md`（或 change 目录名 `v{N}-` 前缀）→ PRD 版本 vN → 原型 worktree = `<workspace>/.worktrees/prd-vN/prototype/`
 - **回退**：该 worktree 不存在时用 `<workspace>/prototype/`，并提示 `tf prototype branch <prd-vN>` 创建
 - **引用**：execution-contract / design.md 中引用的原型页面（`prototype/pages/<page>.html` 等）以此为基准定位；**禁止**引用主干上其他版本的旧原型
 
@@ -111,6 +111,14 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 
 **v0.39.0 主动串行编排**：build-executor 不再负责安排 code-reviewer。workflow-start 会主动串行编排：每个 wave 完成后，workflow-start 会 dispatch code-reviewer 审查。build-executor 只需执行当前 wave，完成后通知 workflow-start。
 
+### Test Infrastructure Check (v0.43.1, before first wave)
+
+开始实施前检测项目测试基础设施，避免测试静默跳过（设计增强方案 v0.18 §76，来源：workflow-feedback 2026-08-06——surefire 2.22.2 不支持 JUnit 5 `@Nested`，64% 测试从未执行但报告 "91 tests pass"）：
+
+1. **Java 项目**：读 `pom.xml` 的 maven-surefire-plugin 版本 + JUnit 版本。
+2. **兼容性判断**：surefire < 2.22.2 且测试计划含 JUnit 5 `@Nested` → 警告"@Nested 自动发现不兼容，建议 flatten 测试类或升级 surefire"。
+3. **沉淀 conventions**：检测结果写入 `.team-flow/conventions/`（项目级测试基础设施约束，v0.11 §33 机制），供后续 change 复用。写入方式沿用下方「阶段转换前规范建议」协议——YAML frontmatter（name/description/date）+ 正文约束，用户确认后追加，更新 date 字段。
+
 ### Planned-Wave Loop
 1. Read the current plan with `tf execution show <change-dir> --json`; only waves shown with `current: true` and `eligible: true` may start. A `retryable: true` wave may only be repaired and re-reviewed; do not dispatch its dependents until its replacement receipt is `pass`. The CLI encodes dependencies in `--wave <id>:<strategy>:<tasks>[:<depends-on,...>]` and rejects a review receipt for a wave whose prerequisites lack current `pass` receipts.
 2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch. If it does not, disclose the unavailable capability and execute the same wave one task at a time without changing its stored strategy.
@@ -124,12 +132,24 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 5. **Do not** attempt to dispatch code-reviewer or write review receipts — that is workflow-start's responsibility.
 6. Critical/Important findings require a `fail` receipt, a focused repair, re-review, then a replacement `pass` receipt. Never advance or close with a missing or failed receipt.
 
+### Wave Verify: Actual Test Count (v0.43.1)
+
+每个 wave 完成、通知 workflow-start 审查前，验证测试**实际执行**的数量（设计增强方案 v0.18 §76，来源：workflow-feedback 2026-08-06——64% 测试静默跳过但报告全绿）：
+
+1. 运行测试套件后，用 `tf test record <change-dir> --from <runner-output-file>` 解析**实际执行数量**（`Tests run: N`）。
+2. 对照 test-matrix 当前 wave 覆盖的用例数（**分母排除 `test_tier=e2e`**——E2E case 由 Playwright 执行，不进入 `mvn test`/`npm test` 的 `Tests run: N`，口径与 code-reviewer Step 5b / release-archivist Step 2b 一致）：实际执行数明显低于预期（< 70%）→ **警告 + 调查**（@Nested 静默跳过、测试未被发现、编译期跳过等），未查明前不得报告 "N tests pass"。
+3. 报告引用实际执行数（`Tests run: N`），而非 BUILD SUCCESS 或编译通过数量。
+
 ### Per-Task Loop
 1. **Dispatch implementer**: Load the template with `tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.
 2. **Handle response**: DONE → generate review package + dispatch reviewer. DONE_WITH_CONCERNS → assess. NEEDS_CONTEXT → provide context. BLOCKED → re-dispatch with better model or escalate.
-3. **Review**: Load `tf runtime asset read skills/build-executor/task-reviewer-prompt.md`. Reviewer returns spec compliance + code quality verdicts with the wave ID, git range, report path, and `pass`/`fail` receipt command.
-4. **Fix**: If Critical or Important issues, write the `fail` receipt, dispatch fix subagent, re-review, and write the replacement `pass` receipt.
-5. **Mark complete**: Append to `.superpowers/sdd/progress.md`: `Task N: complete (commits <base7>..<head7>, review clean)`
+3. **Verify task output（v0.43.1）**：任务标记完成前验证产物——**前置到审查前**（源头校验：文件存在性是审查的前提，让 reviewer 专注质量而非兜底）。设计增强方案 v0.18 §75，来源：workflow-feedback 2026-08-06——Task 标记 [x] 但文件未创建）：
+   - Create 任务：目标文件必须存在且非空（`test -s <path>`）
+   - Modify 任务：目标文件必须有变更（相对 wave base 的 `git diff --name-only` 包含该文件）
+   - 验证失败 → 不标记完成，先补创建/修改——"标记完成"与"文件存在"绑定，杜绝任务状态失真
+4. **Review**（task 级轻量审查；wave 级 code-reviewer 由 workflow-start 主动编排，v0.39.0）: Load `tf runtime asset read skills/build-executor/task-reviewer-prompt.md`. Reviewer returns spec compliance + code quality verdicts with the wave ID, git range, report path, and `pass`/`fail` receipt command.
+5. **Fix**: If Critical or Important issues, write the `fail` receipt, dispatch fix subagent, re-review, and write the replacement `pass` receipt.
+6. **Mark complete**: Append to `.superpowers/sdd/progress.md`: `Task N: complete (commits <base7>..<head7>, review clean)`
 
 ### Model Selection
 Use the configured profile that matches the task role. Resolve it before dispatch:

package/skills/build-executor/implementer-prompt.md

@@ -140,6 +140,7 @@ Subagent (general-purpose):
     - Did I follow TDD if required?
     - Are tests comprehensive?
     - Is the test output pristine (no stray warnings or noise)?
+    - Tests actually EXECUTED (`Tests run: N`), not just compiled — surefire/@Nested version mismatches can silently skip tests (v0.43.1)
     - If test-matrix.md exists: matrix coverage = passed cases / total cases for my module
     - Each case's `design_method` matches the actual test approach (boundary case uses real boundary values, not happy-path disguised as boundary)
 

package/skills/business-analysis/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: business-analysis
+description: "独立业务分析 skill：将任意用户输入整理为结构化 requirement/vN/business-analysis.md，产出 Requirements List 与 Scenario List，支持多轮单问澄清、待办记录、新增/更新模式，写入前必须阻塞用户确认。不写入 ledger.md，不替代 workflow-orchestrator/ce-brainstorm。"
+argument-hint: "[需求/会议/文档描述] [vN 可选]"
+---
+
+# Business Analysis
+
+把任意输入（一句话、文档、会议纪要）整理成 `requirement/vN/business-analysis.md`，只含需求列表与业务场景列表两大板块。
+
+## Primary Goal
+
+- 提取并结构化需求（REQ-xxx）与业务场景（SC-xxx）
+- 通过多轮单问澄清补全缺失维度
+- 用户无法回答的问题记录为 TODO
+- 最终经用户阻塞确认后落盘
+
+## Inputs
+
+| 参数 | 说明 |
+|---|---|
+| `user_input` | 用户原始输入 |
+| `version` | 目标版本，如 `v1`；未提供时自动解析 |
+
+## Mode
+
+- **Create**：`requirement/vN/business-analysis.md` 不存在时新建
+- **Update**：已存在时读取现有条目，追加或修订
+
+## Process
+
+### 1. Resolve Version
+
+按 `references/version-resolution.md` 解析目标 `vN`，判断 Create / Update 模式。若文件已存在，询问用户「继续完善 / 新建版本 / 覆盖」。
+
+### 2. First-Pass Extraction
+
+从 `user_input` 中提取候选 REQ 与 SC，识别缺失维度。先以 🔵 pending 状态写入内部草案。
+
+### 3. One Question at a Time
+
+每次只问 1 个问题，优先选择题，其次开放题。问题应针对当前最大缺失：角色、目标、触发条件、前置条件、约束、可测试验收标准。
+
+### 4. TODO Handling
+
+用户答不上来时，立即在 `## Open Questions / TODOs` 段落记录 `TODO-xxx`，状态 `pending`。相关 REQ/SC 保持 🔵 pending。
+
+### 5. QA Check
+
+每轮更新后运行 `references/qa-checklist.md` 的 5 项 Error 检查。未通过则继续提问，最多 3 轮自修正。
+
+### 6. Final Confirmation
+
+展示完整文档预览，用户选择：
+- **Confirm**：写入文件，所有 🔵 翻转为 ✅ confirmed
+- **Adjust**：返回对话循环
+- **Abort**：保持 pending，不写入最终确认
+
+## Output Contract
+
+只写 `requirement/vN/business-analysis.md`。输出格式见 `references/output-schema.md`。
+
+严格禁止：
+- 写入 `ledger.md`
+- 写入 PRD、流程、架构等下游制品
+- 修改 `.team-flow.yaml`
+
+## Anti-Patterns
+
+- 一次问多个问题
+- 使用泛化角色如 "user"
+- Acceptance 写成不可测试的模糊描述
+- 未确认直接落盘
+
+## References
+
+- `references/output-schema.md` — 输出文档格式
+- `references/qa-checklist.md` — QA 检查标准
+- `references/interaction-rules.md` — 多轮交互与确认规则
+- `references/version-resolution.md` — 版本解析规则

package/skills/business-analysis/references/interaction-rules.md

@@ -0,0 +1,86 @@
+# 业务分析多轮交互规则
+
+本规则约束业务分析 skill 与用户的对话方式、待办处理、确认机制和断点恢复。
+
+## 核心交互原则
+
+### 一次只问一个问题
+
+- 每轮只向用户提出 **1 个** 清晰问题
+- 等待用户回答后再决定下一个问题
+- 禁止一次抛出 2 个及以上问题
+
+### 优先选择题
+
+- 当答案有限时，给出 2–3 个选项并推荐其一
+- 选项后简述每个选项的 trade-off
+- 用户可自由选择或给出新答案
+
+### 开放题仅用于真正开放的场景
+
+- 以下情况使用开放题：
+  - 用户首次输入极短，需要补充背景
+  - 询问 Acceptance 的具体阈值
+  - 确认业务角色名称
+
+## 待办（TODO）处理规则
+
+### 何时记录 TODO
+
+- 用户明确表示 "不知道"、"需要确认"、"后续补充"
+- 问题虽然重要，但当前无法获得可靠答案
+- 继续追问会影响对话收敛效率
+
+### 如何记录 TODO
+
+1. 在 `## Open Questions / TODOs` 段落新增一行：
+   - `TODO-xxx`
+   - 问题原文
+   - 记录日期
+   - 状态 `pending`
+   - 关联的 `REQ-xxx` / `SC-xxx`（如有）
+2. 将相关 REQ/SC 的状态保持为 🔵 pending
+3. 向用户复述已记录的 TODO，确认无误后继续
+
+### TODO 后续回填
+
+- 用户补充答案后，将 TODO 状态改为 `answered`
+- 把答案回填到对应 REQ/SC 的缺失维度
+- 重新运行 QA 检查
+
+## 确认机制
+
+### 增量确认（默认）
+
+- 每轮提取的结构化内容先以 🔵 pending 写入 `business-analysis.md`
+- 最终确认时统一把所有 🔵 翻转为 ✅ confirmed
+- 最终确认前展示完整文档预览，让用户选择 **Confirm / Adjust / Abort**
+
+### 最终确认内容
+
+确认前必须展示：
+- 当前 Requirements List 完整表格
+- 当前 Scenario List 完整表格
+- Open Questions / TODOs 列表
+- 本轮回新增/修改的摘要
+
+### 用户选择
+
+- **Confirm**：写入文件，pending → confirmed
+- **Adjust**：指出需要调整的条目，返回对话循环
+- **Abort**：保持当前 pending 状态，不翻转 confirmed，向用户说明已保存的 pending 内容
+
+## 终止条件
+
+正常终止需满足：
+- QA 所有 Error 检查通过，或
+- 用户明确说 "生成文档" / "确认输出"
+
+安全兜底：
+- 单轮对话最多 10 个问题；达到上限时强制进入最终确认
+
+## 断点恢复
+
+- `business-analysis.md` 本身就是断点载体
+- 恢复时先读取现有文件，把 ✅ confirmed 条目作为基线，🔵 pending 条目作为待确认内容
+- 向用户展示当前进度并询问 "继续完善 / 新建版本 / 覆盖"

package/skills/business-analysis/references/output-schema.md

@@ -0,0 +1,88 @@
+# business-analysis.md 输出格式
+
+本文件定义 `requirement/vN/business-analysis.md` 的精确格式。业务分析 skill 只能输出此格式，不得写入 `ledger.md`、PRD、流程或架构等下游制品。
+
+## 文件定位
+
+- 路径：`requirement/vN/business-analysis.md`
+- 作用：承接对话沉淀，为 PRD 提供需求与场景数据
+- 不直接写入 `requirement/ledger.md`；版本归档由 orchestrator 统一处理
+
+## Frontmatter
+
+```yaml
+---
+version: vN
+status: draft | confirmed
+last_updated: YYYY-MM-DD
+source: business-analysis skill
+---
+```
+
+## 必须包含的两大板块
+
+1. **需求列表（Requirements List）**
+2. **业务场景列表（Scenario List）**
+
+可选追加板块：
+
+3. **Open Questions / TODOs** —— 仅用于记录用户暂时无法回答的问题
+
+## 需求列表格式
+
+每个需求一行，字段如下：
+
+| 字段 | 要求 |
+|------|------|
+| ID | `REQ-xxx`，版本内顺序编号 |
+| Description | 一句话意图，用 SHALL/MUST 表达 |
+| Related Scenarios | `SC-xxx` 列表，逗号分隔 |
+| Status | 🔵 pending / ✅ confirmed |
+| Change History | `[vN.M YYYY-MM-DD create/modify 摘要]` |
+
+## 业务场景格式
+
+每个场景一行，字段如下：
+
+| 字段 | 要求 |
+|------|------|
+| ID | `SC-xxx` |
+| Role | 具体角色，禁止泛化 "user" |
+| Goal | 角色目标 |
+| Trigger | 触发事件/条件 |
+| Precondition | 前置条件 |
+| Constraint | 规则/限制/策略 |
+| Acceptance | 可测试成功条件，必须含具体阈值/字段/结果 |
+| Related Requirements | `REQ-xxx` 列表 |
+| Status | 🔵 pending / ✅ confirmed |
+| Change History | `[vN.M YYYY-MM-DD create/modify 摘要]` |
+
+## Open Questions / TODOs 格式
+
+| 字段 | 要求 |
+|------|------|
+| ID | `TODO-xxx` |
+| Question | 未能回答的问题原文 |
+| Recorded At | YYYY-MM-DD |
+| Status | pending / answered / dropped |
+| Related REQ/SC | 可选 |
+
+## 状态管理
+
+- 仅两种状态：🔵 pending、✅ confirmed
+- 状态转换只能经由用户阻塞确认
+- 确认前必须先通过 QA 检查
+
+## 与 PRD 的映射
+
+| PRD 章节 | 来源内容 |
+|---------|---------|
+| §7 D7.5_系统功能清单 | 需求列表 + 场景关联（REQ / SC） |
+| §8 D7.6_系统功能处理说明书 | 按场景分组的功能模块 |
+
+## 禁止事项
+
+- 禁止在 `business-analysis.md` 中直接写入 `ledger.md`
+- 禁止用泛化角色如 "user" 替代具体业务角色
+- 禁止 Acceptance 写成不可测试的模糊描述
+- 禁止写入业务流程详情（L1-L4、Mermaid、活动表等）

package/skills/business-analysis/references/qa-checklist.md

@@ -0,0 +1,31 @@
+# 业务分析 QA 检查清单
+
+业务分析 skill 在最终确认前必须执行以下 QA 检查。所有 Error 级别项必须全部通过，否则不得将条目标记为 ✅ confirmed。
+
+## Error 级别检查
+
+- [ ] **C1 角色覆盖**：用户输入中提到的所有具体角色都有对应的场景（SC-xxx）覆盖
+- [ ] **C2 六维度齐全**：每个场景都填满 Role / Goal / Trigger / Precondition / Constraint / Acceptance
+- [ ] **C3 REQ 引用存在**：场景中引用的 `REQ-xxx` 必须出现在需求列表中
+- [ ] **C4 对话证据可追溯**：每个场景都能在对话记录或输入中找到证据，禁止编造
+- [ ] **C5 Acceptance 可测试**：验收标准必须具体、可验证，含明确阈值/字段/结果
+
+## Warning 级别检查
+
+- [ ] **W1 角色具体化**：不存在 "user"、"管理员" 等泛化角色，除非已明确定义为业务角色
+- [ ] **W2 需求表述**：需求描述使用 SHALL/MUST，避免 "should"、"可以" 等弱约束
+- [ ] **W3 变更历史**：新增或修改的条目都含变更历史
+
+## QA 不通过时的处理
+
+1. 定位导致失败的条目和维度
+2. 向用户提出**一个**针对性的澄清问题
+3. 根据回答更新文档
+4. 重新运行 QA 检查
+5. 最多允许 3 轮内部自修正；仍无法通过则记录 TODO 并保持 pending
+
+## 待办（TODO）的 QA 规则
+
+- TODO 问题可以暂时不阻塞其他已确认条目的确认
+- 与 TODO 相关的 REQ/SC 必须保持 🔵 pending 状态
+- 用户后续补充答案后，应更新 TODO 状态为 answered 并回填到对应条目

package/skills/business-analysis/references/version-resolution.md

@@ -0,0 +1,41 @@
+# 业务分析版本解析规则
+
+本规则定义业务分析 skill 如何确定目标版本 `vN`。
+
+## 解析顺序
+
+按以下优先级依次解析：
+
+1. **显式参数**：用户在调用 skill 时传入的版本，如 `business-analysis v2`
+2. **运行时配置**：`tf runtime config --get active.requirement`（若返回有效值）
+3. **目录扫描**：读取 `requirement/` 下已有的 `vN` 目录，取最大 N
+4. **默认回退**：以上皆无时使用 `v1`
+
+## 目录扫描规则
+
+- 只识别 `requirement/vN/` 形式目录，其中 N 为正整数
+- 忽略非版本目录（如 `archived/`、`draft/`）
+- 若存在 `v1`、`v2`、`v3`，则取 `v3`
+
+## 模式判断
+
+解析出版本后，判断当前是 Create 还是 Update 模式：
+
+| 条件 | 模式 | 行为 |
+|---|---|---|
+| `requirement/vN/business-analysis.md` 不存在 | Create | 新建文件 |
+| 文件已存在 | Update | 读取现有条目，追加或修订 |
+
+## 已存在文件的处理
+
+检测到文件已存在时，必须向用户询问以下三者之一：
+
+- **继续完善**：在当前版本基础上追加/修改条目
+- **新建版本**：创建 `v(N+1)/business-analysis.md`，旧版本保持 archived
+- **覆盖**：清空当前版本重新生成（不推荐，需用户明确确认）
+
+## 版本号输出
+
+- 最终输出的 `business-analysis.md` frontmatter 中必须包含 `version: vN`
+- Change History 中的版本号采用 `vN.M` 形式，其中 M 为本次编辑的次要版本（同一 vN 内递增）
+- 首次创建使用 `vN.1`，后续补充依次递增