@xulthekl/team-flow 0.39.0 → 0.40.1

package/scripts/lib/execution-plan.mjs

@@ -5,6 +5,7 @@ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { computeArtifactsHash, computeContractHash } from './hash.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { readState } from './state-loader.mjs';
+import { detectWorkspaceRoot, findSubRepo } from './git-utils.mjs';
 
 export const EXECUTION_MODES = ['inline', 'batch-inline', 'sdd'];
 
@@ -130,7 +131,7 @@ export function validatePlan(changeDir, plan) {
   return { valid: failures.length === 0, failures, plan };
 }
 
-export function recordReview(changeDir, waveId, receipt) {
+export function recordReview(changeDir, waveId, receipt, repoPath) {
   const plan = readPlan(changeDir);
   const validation = validatePlan(changeDir, plan);
   if (!validation.valid) throw new Error(`Cannot record a review for an invalid execution plan: ${validation.failures.join('; ')}`);
@@ -145,7 +146,7 @@ export function recordReview(changeDir, waveId, receipt) {
   }
   for (const field of ['base', 'head']) requireText(receipt?.[field], `receipt.${field}`);
   const report = validateReviewReportEvidence(changeDir, receipt?.report);
-  const { base, head } = validateReviewRange(changeDir, receipt.base, receipt.head);
+  const { base, head, subRepoPath } = validateReviewRange(changeDir, receipt.base, receipt.head, repoPath);
   // v0.13 §51.2：测试统计为可选证据字段（提供时必须为非负整数）。
   // 硬门禁在入口（test-matrix-ready）与 closing（tests-passing），此处只沉淀证据，
   // 避免单 wave 零测试造成 BUG-A 式过严死锁（DDL/脚手架类 wave 可能合理无测试）。
@@ -166,6 +167,9 @@ export function recordReview(changeDir, waveId, receipt) {
     head,
     report,
     ...(tests ? { tests } : {}),
+    // Persist repo path when SHA was resolved in a sub-repository, so
+    // readCurrentReview can re-validate without re-scanning.
+    ...(subRepoPath ? { repo: relative(changeDir, subRepoPath) } : {}),
     plan_hash: plan.hash,
     plan_revision: plan.revision,
     recorded_at: new Date().toISOString(),
@@ -187,7 +191,10 @@ export function readCurrentReview(changeDir, waveId, plan = readPlan(changeDir))
   try {
     const receipt = JSON.parse(readFileSync(filePath, 'utf8'));
     if (receipt?.plan_hash !== plan.hash || receipt?.plan_revision !== plan.revision) return null;
-    const range = validateReviewRange(changeDir, receipt?.base, receipt?.head);
+    // When the receipt records a repo path (sub-repo scenario), use it for
+    // SHA re-validation.  Otherwise fall back to the default main-repo path.
+    const repoPath = receipt?.repo ? resolve(changeDir, receipt.repo) : undefined;
+    const range = validateReviewRange(changeDir, receipt?.base, receipt?.head, repoPath);
     if (receipt.base !== range.base || receipt.head !== range.head) return null;
     // A passing receipt is current evidence only while its referenced report
     // remains safe and readable. Recheck it here because reports can be
@@ -276,10 +283,74 @@ function getPhysicalReviewsDirectory(changeDir) {
   return { changeRoot, reviewsDir: directory };
 }
 
-function validateReviewRange(changeDir, base, head) {
-  const gitRoot = getGitRoot(changeDir);
-  const resolvedBase = resolveGitCommit(gitRoot, base, 'base');
-  const resolvedHead = resolveGitCommit(gitRoot, head, 'head');
+function validateReviewRange(changeDir, base, head, repoPath) {
+  const gitRoot = resolveGitRoot(changeDir, repoPath);
+
+  let resolvedBase, resolvedHead, subRepoPath;
+  try {
+    resolvedBase = resolveGitCommit(gitRoot, base, 'base');
+    resolvedHead = resolveGitCommit(gitRoot, head, 'head');
+  } catch (primaryError) {
+    // Sub-repo fallback: when SHA is not in the main repo, scan workspace
+    // children for a sub-repository that contains it (e.g. bff/, ui/).
+    // Only attempt when --repo was not explicitly provided.
+    if (repoPath) throw primaryError;
+
+    const workspaceRoot = detectWorkspaceRoot(changeDir);
+    if (!workspaceRoot) throw primaryError;
+
+    const subRoot = findSubRepo(workspaceRoot, head);
+    if (!subRoot) throw primaryError;
+
+    resolvedBase = resolveGitCommit(subRoot, base, 'base');
+    resolvedHead = resolveGitCommit(subRoot, head, 'head');
+    subRepoPath = subRoot;
+  }
+
+  // Track when SHA was resolved outside the changeDir's own repo.
+  // This happens either through automatic fallback (subRepoPath set above)
+  // or through explicit --repo pointing to a different repository.
+  if (!subRepoPath && repoPath) {
+    const defaultRoot = resolveGitRoot(changeDir);
+    if (gitRoot !== defaultRoot) subRepoPath = gitRoot;
+  }
+
+  const effectiveRoot = subRepoPath || gitRoot;
+  const result = validateResolvedRange(effectiveRoot, resolvedBase, resolvedHead);
+  return { ...result, subRepoPath };
+}
+
+/**
+ * Resolve the git root for SHA verification. Honors an explicit --repo path;
+ * otherwise uses the changeDir's own git repository.
+ */
+function resolveGitRoot(changeDir, repoPath) {
+  if (repoPath) {
+    const absRepo = isAbsolute(repoPath) ? repoPath : resolve(changeDir, repoPath);
+    try {
+      return execFileSync('git', ['-C', absRepo, 'rev-parse', '--show-toplevel'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      throw new Error(`--repo path '${repoPath}' is not inside a Git work tree`);
+    }
+  }
+  try {
+    return execFileSync('git', ['-C', changeDir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    throw new Error('Review receipts require the change directory to be inside a Git work tree');
+  }
+}
+
+/**
+ * Validate a resolved SHA range: base must differ from head, and base must
+ * be an ancestor of head. Shared by both primary and sub-repo paths.
+ */
+function validateResolvedRange(gitRoot, resolvedBase, resolvedHead) {
   // v0.13 §51.1：禁止空 diff review（base === head）。
   // C1-domain-policy 现场曾出现 6 个 receipt 全部 base==head==初始 commit，
   // 即 review 对空 diff 进行。本校验同时强制"每 wave 落 commit"的纪律。
@@ -299,17 +370,6 @@ function validateReviewRange(changeDir, base, head) {
   return { base: resolvedBase, head: resolvedHead };
 }
 
-function getGitRoot(changeDir) {
-  try {
-    return execFileSync('git', ['-C', changeDir, 'rev-parse', '--show-toplevel'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-  } catch {
-    throw new Error('Review receipts require the change directory to be inside a Git work tree');
-  }
-}
-
 function resolveGitCommit(gitRoot, revision, field) {
   try {
     return execFileSync('git', ['-C', gitRoot, 'rev-parse', '--verify', `${revision}^{commit}`], {

package/scripts/lib/git-utils.mjs

@@ -0,0 +1,90 @@
+/**
+ * Shared git utilities for multi-repo workspace support.
+ *
+ * team-flow workspaces may contain multiple independent git repositories
+ * (e.g. bff/ and ui/ alongside the main repo). These helpers provide
+ * consistent root detection and sub-repo discovery used by:
+ * - execution-plan.mjs  (SHA resolution across repos)
+ * - arch-merge.mjs      (git add/commit in correct repo)
+ * - cmd-prototype.mjs   (workspace root detection)
+ * - cmd-publish.mjs     (workspace root detection)
+ * - ensure-branch.mjs   (workspace root detection for worktree isolation)
+ * - cmd-deisolate.mjs   (workspace root detection for deisolation)
+ *
+ * @module git-utils
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+
+/**
+ * Detect the workspace root from a changeDir path by looking for the
+ * standard `changes/<name>/` directory layout.
+ *
+ * @param {string} changeDir - Absolute or relative path to a change directory
+ * @returns {string|null} Workspace root (parent of `changes/`), or null if
+ *   changeDir is not inside a standard `changes/` layout
+ */
+export function detectWorkspaceRoot(changeDir) {
+  const abs = resolve(changeDir);
+  const changesIdx = abs.lastIndexOf(sep + 'changes' + sep);
+  return changesIdx > 0 ? abs.slice(0, changesIdx) : null;
+}
+
+/**
+ * Get the git repository root for a given filesystem path.
+ *
+ * @param {string} path - Any path inside a git work tree
+ * @returns {string} Absolute path to the git repository root
+ * @throws {Error} When path is not inside a git work tree
+ */
+export function getGitRoot(path) {
+  try {
+    return execFileSync('git', ['-C', path, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    throw new Error(`Path '${path}' is not inside a Git work tree`);
+  }
+}
+
+/**
+ * Scan direct children of workspaceRoot for sub-repositories that contain
+ * the given git revision.  A sub-repository is any direct child directory
+ * that has a `.git` entry (directory for normal repos, file for worktrees
+ * and submodules).
+ *
+ * Used as a fallback when a SHA cannot be found in the main repo — if the
+ * workspace contains independent code repos (bff/, ui/, etc.), the commit
+ * may live there instead.
+ *
+ * @param {string} workspaceRoot - Workspace root directory to scan
+ * @param {string} revision - Git revision to look up (SHA, branch, tag)
+ * @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) {
+  let entries;
+  try {
+    entries = readdirSync(workspaceRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const candidate = join(workspaceRoot, entry.name);
+    if (!existsSync(join(candidate, '.git'))) continue;
+    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);
+    } catch {
+      // Not in this sub-repo, continue scanning
+    }
+  }
+  return null;
+}

package/skills/build-executor/SKILL.md

@@ -107,19 +107,22 @@ Boundaries: if any task touches >1 module, involves schema/API/config changes, o
 
 ## SDD Workflow
 
-For full/hotfix by default. Dispatch according to the persisted plan, review each planned wave, and run a final broad review after all waves.
+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。
 
 ### 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.
 3. A `serial` wave dispatches one task at a time in listed order.
-4. After every wave, write a non-empty persisted regular-file review report (separate from the implementer's report), then record exactly one receipt that names that review report:
-   ```bash
-   tf execution review <change-dir> \
-     --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>
-   ```
-   Do not begin a dependent wave until its predecessor receipt is `pass`.
-5. 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.
+4. After every wave, notify workflow-start via SendMessage that the wave is complete and needs review. Include:
+   - Wave ID
+   - Worktree path
+   - Branch
+   - Repositories and commit SHAs (base + head)
+   - Summary of changes
+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.
 
 ### 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.
@@ -149,7 +152,7 @@ Track in `.superpowers/sdd/progress.md`. Check for existing ledger — completed
 
 ## Inline Execution Mode
 
-Only after a user-confirmed `inline` selection is recorded by `tf execution plan --confirm`; a non-recommended selection also records `--acknowledge-recommendation`. Executes in the current session and still writes one review receipt per planned wave.
+Only after a user-confirmed `inline` selection is recorded by `tf execution plan --confirm`; a non-recommended selection also records `--acknowledge-recommendation`. Executes in the current session. After each wave, notify workflow-start for review (do NOT attempt to write review receipts).
 
 Per-task: extract brief → write failing test → confirm failure → implement → confirm green → checkpoint review (done-when criteria, SHALL/MUST verification) → commit → save a task-level recovery checkpoint when another task remains → append to progress ledger.
 
@@ -180,7 +183,7 @@ DP-5 (debug escalation): `tf state set <change-dir> dp_5_result "<resolution>"`
 
 ## Completion Standard
 
-Don't report completion until: tests pass, contract obligations satisfied, review blockers resolved, every planned wave has a current `pass` receipt, final review is complete, and workflow is ready for `release-archivist`.
+Don't report completion until: tests pass, contract obligations satisfied, and every planned wave has been notified to workflow-start for review. Review blockers are handled by workflow-start via code-reviewer dispatch.
 
 ## Exception Handling
 

package/skills/ce-brainstorm/SKILL.md

@@ -19,7 +19,7 @@ Brainstorming answers **WHAT** to build through collaborative dialogue, producin
 
 > **显式参数规约**：orchestrator 调用时必须传入 `mode: orchestrated`。ce-brainstorm 检测到该参数即跳过 Phase 3.5 并在输出中回执"原型循环已委托编排层"。未收到该参数时默认为 standalone 模式。
 >
-> **重要：`orchestrated` 模式仅跳过 Phase 3.5（原型内循环），Phase 0（含 PRD 模板选择）、Phase 1、Phase 2、Phase 3 均正常执行，不可跳过。**
+> **重要：`orchestrated` 模式仅跳过 Phase 3.5（原型内循环）。Phase 0（含 PRD 模板选择）、Phase 1（含 1.4/1.5/1.6）、Phase 2、Phase 3、QA-4、Phase 3.6、版本归档均正常执行，不可跳过。**
 
 ## Core Principles
 
@@ -119,6 +119,12 @@ For detailed routing logic, read `references/phase0-routing.md`. Summary:
 
 **1.3 Dialogue** — Follow Interaction Rules. Fire blindspot gate (if tripwire armed) and visual-probe gate (before first shape decision). Rigor probes fire as open-ended questions before Phase 2. Before exit: integration check for non-obvious consequences. **Exit when**: primary actor, outcome, scope, success criteria all known or recorded as assumptions.
 
+**1.4 Dialogue Log Persistence** — Automated step, no user interaction. Trigger: Phase 1.3 dialogue exits. Traverse each Q&A round extracting original text + decisions, generate dialogue summary and decision summary table. Write to `requirement/vN/dialogue-log.md` (create or append). No ledger update.
+
+**1.5 Business Scenario Analysis** — Read `references/business-scenarios.md` for methodology. Trigger: Phase 1.4 completed. Extract business scenarios from dialogue and context, produce QA-1 quality check, then **blocking question** for user confirmation. Output: `requirement/vN/business-analysis.md` (requirements + scenarios sections). Status marked 🔵 pending confirmation, ✅ confirmed on user approval. No ledger update at this stage.
+
+**1.6 Business Process Analysis** — Read `references/business-processes.md` for methodology. Trigger: Phase 1.5 confirmed (✅). Extract business processes, produce QA-2 quality check, then **blocking question** for user confirmation. Output: update `requirement/vN/business-analysis.md` (processes section + scenario/requirement association fields). Status marked 🔵 pending, ✅ confirmed on approval. No ledger update at this stage.
+
 ### Phase 2: Explore Approaches
 
 **Load brainstorm profile.** If `BRAINSTORM_PROFILE_PATH` is set, read it. Each approach must address core thinking dimensions; note irrelevant dimensions.
@@ -133,8 +139,15 @@ Propose **2-3 approaches** (or recommend directly if one is clearly best). Use n
 
 **Read `references/synthesis-summary.md` before composing.** Surface scoping synthesis — user's last chance to correct scope. Fires for all tiers. Path A (announce-only) for Lightweight + no blocking questions; Path B (confirmation gate) for all others. 2.6: dispatch claim verifier during Path B confirmation wait.
 
+**QA-3 quality check** fires after synthesis draft is complete, before the blocking question. Synthesis must reference confirmed scenario IDs (SC-xxx) and process IDs (BP-xxx) as evidence anchors. Unconfirmed (🔵) items are flagged in Call outs section.
+
 ### Phase 3: Generate PRD Document
 
+**Inputs** (read before generating PRD):
+- `requirement/ledger.md` — all requirement/scenario/process items and their associations
+- `requirement/vN/dialogue-log.md` — §1.2 revision record reference path
+- `requirement/vN/business-analysis.md` — data source for §2/§3/§7/§8
+
 **⛔ MANDATORY：生成PRD文档前，必须先读取 `references/brainstorm-sections.md`**
 
 **§8.4 功能模块提取规则（关键规则，必须遵守）**：
@@ -151,12 +164,62 @@ Propose **2-3 approaches** (or recommend directly if one is clearly best). Use n
 - **⛔ 错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节
 - **⛔ 正确行为**：充分利用原始需求文档的详细内容，保持信息完整性
 
-Read `references/brainstorm-sections.md` for doc-warranted criteria. If warranted: read template from `PRD_TEMPLATE_PATH`, fill via `references/prd-mapping.md`, write to `prd/{ITERATION_VERSION}/prd.md`. Vocabulary capture: update `CONCEPTS.md` with resolved domain terms (only if it exists).
+Read `references/brainstorm-sections.md` for doc-warranted criteria. If warranted: read template from `PRD_TEMPLATE_PATH`, fill via `references/prd-mapping.md`, write to `requirement/{ITERATION_VERSION}/prd.md`. Vocabulary capture: update `CONCEPTS.md` with resolved domain terms (only if it exists).
 
 ### Phase 3.5: Prototype Inner Loop
 
 **`orchestrated` mode skips this phase.** For standalone: read `references/prototype-loop.md`. Trigger: PRD has UI functions. Steps: produce prototype → review vs PRD → fix loop (max 3) → completeness review → freeze PRD.
 
+### QA-4: PRD Quality Check
+
+Fires after Phase 3 (or Phase 3.5 if prototype loop ran). Read `references/evidence-chain-validation.md` for QA-4 criteria. Evaluates PRD completeness and traceability against business analysis artifacts.
+
+### Phase 3.6: PRD ↔ Scenario/Process Bidirectional Validation
+
+**Read `references/evidence-chain-validation.md` for full methodology.** Automated validation; CONDITIONAL_PASS requires user annotation of exempt items. Performs five validation dimensions (V1–V5) ensuring every requirement traces to scenarios and processes, and vice versa.
+
+**Routing**: PASS → proceed to version archiving; CONDITIONAL_PASS → proceed with documented caveats; FAIL → return to Phase 3 for revision.
+
+### Version Archiving
+
+Automated step, no user interaction. Trigger: Phase 3.6 result is PASS or CONDITIONAL_PASS.
+
+**Pre-checks** (all must pass, otherwise abort):
+1. All requirements (REQ-xxx) confirmed ✅
+2. All scenarios (SC-xxx) confirmed ✅
+3. All processes (BP-xxx) confirmed ✅
+4. Phase 3.6 result is PASS or CONDITIONAL_PASS
+
+**Processing**: batch-write all confirmed items to `requirement/ledger.md`; add archiving record with `archived` frontmatter; update `doc/active-registry/active-items.md` with current active items. Exit → ce-plan.
+
 ### Phase 4: Handoff
 
 Read `references/handoff.md` — option set, visibility conditions, dispatch instructions all live there. Pass PRD path + prototype path (if loop ran) to `ce-plan`.
+
+## Artifact Structure
+
+```
+requirement/
+├── ledger.md                          # Master ledger (all items, cross-version summary)
+├── vN/                                # Iteration version
+│   ├── prd.md                         # PRD document
+│   ├── dialogue-log.md                # Dialogue log (Phase 1.4 output)
+│   └── business-analysis.md           # Business analysis (requirements + scenarios + processes)
+doc/
+└── active-registry/
+    └── active-items.md                # Current active items full view
+```
+
+## Status Management
+
+Two statuses only: 🔵 pending confirmation / ✅ confirmed.
+
+- Phase 1.5/1.6 confirmation: writes `business-analysis.md` only, no ledger update.
+- Version archiving: batch-writes to `ledger.md`.
+
+## Deprecation Handling
+
+When a requirement/scenario/process is deprecated:
+1. Remove the entry from `requirement/ledger.md`
+2. Remove the entry details from `requirement/vN/business-analysis.md`
+3. Update `doc/active-registry/active-items.md`

package/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -164,13 +164,42 @@ Extension dimensions follow the normal conditional-fill rules below.
   of what was brainstormed.
 - **§2 业务流程一览** — filled from brainstorm's Key Flows and Actors. Each
   identified business process gets a row in the flow overview table.
+
+  **数据来源**：`requirement/vN/business-analysis.md` 业务流程一览表。
+  流程按四级层级组织：
+  - **L1 流程分组**：顶层业务域（如"采购管理""销售管理"）
+  - **L2 业务过程**：分组下的端到端业务过程
+  - **L3 业务活动**：过程中的关键活动节点
+  - **L4 子流程/操作步骤**：活动内的具体操作
+
+  §2 总览表必须覆盖 business-analysis.md 中识别的全部 L1–L4 流程条目，
+  每个条目一行，保留原始层级编号（BP-xxx）。
 - **§7 D7.5_系统功能清单** — filled from brainstorm's Requirements. Each
   requirement maps to a system function entry.
 
+  **三 ID 关联规则**：每个系统功能条目必须标注三个关联 ID：
+  | 字段 | 说明 | 示例 |
+  |------|------|------|
+  | 关联需求 ID | 对应 PRD 中的需求编号 | REQ-xxx |
+  | 关联场景 ID | 对应的业务场景编号 | SC-xxx |
+  | 关联流程步骤 | 对应的业务流程活动编号 | BP-xxx |
+
+  三 ID 完整是 §7 的最低质量门槛——缺失任一 ID 的条目视为不完整，
+  需回溯 brainstorm 对话或 business-analysis.md 补齐。
+
 ### Conditionally filled (when dialogue covers the topic)
 
 - **§3 D7.1_业务流程** — filled when brainstorm produced multi-step Key Flows
   with enough detail for process diagrams.
+
+  **数据来源**：`requirement/vN/business-analysis.md` 流程详情部分。
+  每个流程包含：
+  - **Mermaid 流程图**：从 business-analysis.md 提取对应流程的 mermaid 定义，
+    保持活动节点与 BP-xxx 编号一致。
+  - **活动一览表**：列出该流程下所有活动节点，包含活动编号（BP-xxx）、
+    活动名称、触发条件、执行角色、输入/输出、业务规则。
+
+  §3 按流程逐一展开，流程编号与 §2 总览表对齐。
 - **§4 D7.2_画面原型及设计** — filled when brainstorm involves UI/visual
   components. Prototype references go here.
 - **§6 D7.4_业务术语字典** — filled with domain terms defined during brainstorm
@@ -180,6 +209,17 @@ Extension dimensions follow the normal conditional-fill rules below.
   §8.4 功能模块 from Requirements. Hardware/network/performance sections
   retain placeholders.
 
+  **按流程组织结构**：§8 的功能模块按业务流程分组（BP-xxx），而非按
+  功能域平铺。每个功能模块必须标注所属流程：
+  ```
+  ### 8.4.x [功能模块名]
+  - **所属流程**：BP-xxx [流程名称]
+  - **关联需求**：REQ-xxx, REQ-xxx
+  - **关联场景**：SC-xxx
+  ```
+  流程分组顺序与 §2 总览表、§3 流程详情保持一致。同一流程下的功能
+  模块紧邻排列，便于按流程维度审阅功能完整性。
+
 ### Always placeholder (belong to later processes)
 
 - **§5 D7.3_报表清单** — retains template placeholder. Report details are
@@ -198,13 +238,15 @@ dialogue. Filling a chapter with placeholder content is worse than leaving it
 as template placeholder.
 
 - **§2 业务流程一览** — fill when brainstorm identified business processes,
-  user journeys, or system interactions. Each distinct process gets a row. Skip
-  rows for processes not discussed.
+  user journeys, or system interactions. Data source: `requirement/vN/business-analysis.md`
+  流程清单 L1–L4 层级表。Each distinct process gets a row with its BP-xxx
+  编号, preserving the four-level hierarchy. Skip rows for processes not discussed.
 
 - **§3 D7.1_业务流程** — fill when brainstorm produced detailed multi-step
-  flows with enough granularity for process diagrams. Include the flow diagram
-  placeholder and step-by-step descriptions. Skip when flows are high-level
-  only.
+  flows with enough granularity for process diagrams. Data source:
+  `requirement/vN/business-analysis.md` 流程详情（mermaid 流程图 + 活动一览表）。
+  Include the mermaid flow diagram and activity table per process. Skip when
+  flows are high-level only.
 
 - **§4 D7.2_画面原型及设计** — fill when brainstorm involves UI changes.
   Include module names, page names, and prototype references. Skip entirely
@@ -216,12 +258,14 @@ as template placeholder.
 
 - **§7 D7.5_系统功能清单** — fill from brainstorm Requirements. Each R-ID
   maps to a system function entry with the requirement's intent as the function
-  description.
+  description. Each entry must annotate three IDs: 关联需求 ID (REQ-xxx) +
+  关联场景 ID (SC-xxx) + 关联流程步骤 (BP-xxx).
 
 - **§8 D7.6_系统功能处理说明书** — partially fill §8.2 when dialogue covered
-  permissions, interactions, or exception handling. Fill §8.4 from Requirements.
-  Skip §8.3 (hardware/network) and §8.5 (non-functional) unless the brainstorm
-  explicitly covered these.
+  permissions, interactions, or exception handling. Fill §8.4 from Requirements,
+  organized by process (BP-xxx grouping): each function module annotates its
+  所属流程 (BP-xxx). Skip §8.3 (hardware/network) and §8.5 (non-functional)
+  unless the brainstorm explicitly covered these.
 
   **§8.4 功能模块提取规则**：
   - **详细程度**：保留原始需求文档中的关键细节，不要过度概括

package/skills/ce-brainstorm/references/business-processes.md

@@ -0,0 +1,140 @@
+# Phase 1.6 — Business Process Analysis
+
+Detailed process derivation and structured output logic for Phase 1.6. The main SKILL.md describes the high-level flow; this reference contains step-level methodology, output formats, QA checks, and ledger rules.
+
+## Trigger & Input
+
+**Trigger**: Phase 1.5 completed (all scenarios confirmed).
+**Tier**: All.
+**Nature**: Analysis + user confirmation loop until confirmed.
+
+**Input**:
+- `requirement/vN/business-analysis.md` — confirmed scenarios with IDs (✅ SC-xxx)
+- `requirement/ledger.md` — archived process records from prior versions
+
+## Step 1: Derive Processes from Scenarios
+
+For each confirmed scenario, derive a step sequence using BPMN thinking:
+
+- **Roles / swimlanes**: identify all actors (human, system, external)
+- **Activities**: discrete work units each actor performs
+- **Events**: start event, intermediate events, end event
+- **Gateways**: decision points that branch the flow (exclusive / parallel / inclusive)
+
+Produce one draft process per scenario. A scenario may map to one or more L4 sub-processes.
+
+## Step 2: Compare Against Existing Processes
+
+Read both sources:
+
+1. `requirement/ledger.md` — archived processes from prior versions
+2. `requirement/vN/business-analysis.md` — processes already documented in the current version
+
+Classify each draft process:
+
+| Outcome | Action |
+|---------|--------|
+| New process | Create entry with status 🔵 待确认 |
+| Optimised process | Create a changed version in current `business-analysis.md` |
+| Unchanged | Skip — no entry needed |
+
+## Step 3: Structured Output (Three Forms)
+
+### 3.1 L1–L4 Classification Table
+
+Fill the business process overview table (aligns with PRD §2):
+
+| L1 Group | L2 Category | L3 Process | L4 Sub-process | Status | Related Scenarios |
+|----------|-------------|------------|----------------|--------|-------------------|
+
+**Hierarchy**: L1 → L2 → L3 → L4. L3 is a collection of L4 sub-processes. Each ledger record corresponds to one L4. **L4 is the minimum recording unit.**
+
+### 3.2 Process Flow Diagram
+
+Output a mermaid flowchart for each L4 sub-process:
+
+```mermaid
+flowchart TB
+  subgraph RoleA[Role A]
+    A1[Step 1] --> A2[Step 2]
+  end
+  subgraph RoleB[Role B]
+    B1[Step 3] --> B2{Decision}
+    B2 -->|Yes| B3[Step 4]
+    B2 -->|No| B4[Exception]
+  end
+```
+
+**Rules**: Must use `flowchart TB`; must partition by role swimlanes (`subgraph`); every gateway must label all branches; exception paths must terminate explicitly.
+
+### 3.3 Activity Table (9 Columns — Hard Constraint)
+
+One table per L4 sub-process:
+
+| Step | Activity | Execution Steps | Role | Trigger | Input | Output | Related Function | Exception Handling |
+|------|----------|-----------------|------|---------|-------|--------|------------------|--------------------|
+
+**All 9 columns are mandatory.** "Execution Steps" describes the concrete actions within each activity — must not be empty. "Related Function" references FUNC-xxx IDs or is marked "TBD". "Exception Handling" must cover every exception branch visible in the flow diagram.
+
+### 3.4 Process Attribute Block
+
+Each L4 sub-process carries a property header:
+
+| Field | Description |
+|-------|-------------|
+| Process ID | BP-xxx |
+| Status | 🔵 待确认 / ✅ 已确认 |
+| L1 / L2 / L3 / L4 | Full classification path |
+| Related Scenarios | SC-xxx IDs |
+| Trigger Event | What initiates the process |
+| End Condition | What terminates the process |
+| Involved Roles | All actors |
+
+## Step 4: Reverse Reference Update
+
+After producing the three output forms, update `business-analysis.md`:
+
+- Each scenario's "Related Process" field → list associated BP-xxx IDs
+- Each requirement's "Related Process" field → list associated BP-xxx IDs
+
+**Do not update `ledger.md`.** Ledger entries are written in bulk during version archiving, not during analysis.
+
+## Step 4.5: QA-2 Process Quality Check
+
+Dispatch `process-quality-checker` sub-agent. Evaluate 9 checks:
+
+| ID | Category | Check | Severity |
+|----|----------|-------|----------|
+| C1 | Completeness | Every confirmed scenario (✅ SC-xxx) has ≥1 related process | Error |
+| C2 | Completeness | Every process has L1–L4 fully filled (L4 non-empty) | Error |
+| C3 | Completeness | Every process has a mermaid flow diagram | Error |
+| C4 | Completeness | Activity table has 9 columns and every step has "Execution Steps" filled | Error |
+| C5 | Consistency | Process "Related Scenarios" IDs exist in the scenario registry | Error |
+| C6 | Consistency | Flow diagram steps correspond 1:1 with activity table steps | Error |
+| C7 | Consistency | Reverse references complete — related scenarios' "Related Process" field updated | Warning |
+| C8 | Accuracy | Exception handling covers all exception branches in the flow diagram | Warning |
+| C9 | Accuracy | "Related Function" IDs are valid (FUNC-xxx exists or marked TBD) | Warning |
+
+**Routing**: All Error checks PASS → proceed to Step 5. Any Error FAIL → return to correct (max 3 rounds). Warnings are reported but do not block.
+
+## Step 5: Display & Confirmation
+
+Present all three output forms to the user as a blocking question:
+
+- ✅ **Confirmed** → upgrade status to ✅ 已确认; write into current version `business-analysis.md`; exit (no ledger update).
+- ✏️ **Adjust** → apply feedback; return to Step 3; loop until confirmed.
+
+## Write Rules
+
+| Target | When | What |
+|--------|------|------|
+| `business-analysis.md` (current version) | On confirmation | Process details + reverse references |
+| `ledger.md` | Never during Phase 1.6 | Bulk-written at version archiving only |
+
+## Deprecation Handling
+
+When a process is deprecated, execute all three steps:
+
+1. Delete the record from `ledger.md`
+2. Delete the detail block from the version's `business-analysis.md`
+3. Update `doc/active-registry/active-items.md`