@xulthekl/team-flow 0.39.1 → 0.40.1

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/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`

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

@@ -0,0 +1,122 @@
+# Phase 1.5 — Business Scenario Analysis
+
+Detailed scenario extraction and validation logic for Phase 1.5. Triggered after Phase 1.4 completes; applies to all tiers. This phase is analytical with user confirmation — loops until the user confirms.
+
+## Trigger & Input
+
+**Trigger**: Phase 1.4 completed.
+
+**Input files**:
+- `requirement/vN/dialogue-log.md` — conversation evidence
+- `requirement/ledger.md` — archived scenario entries (read-only during this phase)
+- `requirement/vN/business-analysis.md` — current version scenarios (if any exist)
+
+## Step 1: Extract Candidate Scenarios
+
+Read `dialogue-log.md` and identify all business scenarios implied by the conversation. A candidate scenario is a discrete business activity involving one or more roles pursuing a goal under specific conditions. Extract:
+
+- The roles mentioned or implied
+- The goals each role pursues
+- Triggering conditions and preconditions
+- Constraints and acceptance criteria mentioned
+
+Output a raw candidate list — one entry per distinct business activity. Do not merge or deduplicate yet.
+
+## Step 2: Compare with Existing Scenarios
+
+Read two sources:
+
+1. **Archived entries** — `requirement/ledger.md` (scenarios from previous versions that have been archived)
+2. **Current version** — `requirement/vN/business-analysis.md` (scenarios already drafted in this version)
+
+For each candidate from Step 1, classify:
+
+| Classification | Action |
+|---|---|
+| **New** — no matching entry in either source | Create entry with status 🔵 pending |
+| **Optimized** — existing entry needs revision per new evidence | Create a revised version in current `business-analysis.md`, mark change type |
+| **Unchanged** — existing entry already covers it | Skip |
+
+Matching criteria: same business activity (role + goal overlap), not merely same domain.
+
+## Step 3: Six-Dimension Structuring
+
+For each new or optimized scenario, fill all six dimensions:
+
+| Dimension | Description |
+|---|---|
+| **Role** | Who performs this activity (specific role, not generic "user") |
+| **Goal** | What the role aims to achieve |
+| **Trigger** | What event or condition initiates this scenario |
+| **Precondition** | What must be true before the scenario can start |
+| **Constraint** | Rules, limits, or policies that bound the scenario |
+| **Acceptance** | Testable conditions that prove the scenario succeeded |
+
+**Entry metadata**:
+
+| Field | Value |
+|---|---|
+| Scenario ID | `SC-xxx` (sequential within version) |
+| Status | 🔵 pending |
+| Related requirements | `REQ-xxx` references |
+| Related process | Process name or ID if applicable |
+| Change history | Version, date, change type (create/modify), summary |
+
+## Step 3.5: QA-1 Quality Check
+
+Dispatch `scenario-quality-checker` sub-agent after structuring completes.
+
+**Check items**:
+
+| ID | Category | Check | Level |
+|---|---|---|---|
+| C1 | Completeness | All roles from dialogue-log have corresponding scenario coverage | Error |
+| C2 | Completeness | Every scenario has all six dimensions filled | Error |
+| C3 | Consistency | Related requirement IDs (`REQ-xxx`) exist in the requirement list | Error |
+| C4 | Consistency | New scenarios do not overlap/conflict with archived ledger entries | Warning |
+| C5 | Accuracy | Each scenario has traceable evidence in dialogue-log (not fabricated) | Error |
+| C6 | Accuracy | Acceptance criteria are testable (specific conditions, not vague) | Warning |
+| C7 | Completeness | Optimized scenarios include a change reason | Warning |
+
+**Routing**:
+
+- **PASS** (0 Errors) → proceed to Step 4
+- **FAIL** (≥1 Error) → return to Step 3, fix flagged items, re-check
+- **Maximum 3 rounds** — if still failing after round 3, escalate to user for decision
+
+Warnings are reported but do not block progression.
+
+## Step 4: Present & Confirm (Blocking Question)
+
+Display all scenarios (new + optimized) with full six-dimension detail. Ask the user for formal confirmation:
+
+- **✅ Confirm** → upgrade status to ✅ confirmed, write to `requirement/vN/business-analysis.md`, exit phase
+- **✏️ Adjust** → apply user feedback, return to Step 3, re-run QA-1
+
+This is a blocking question — do not proceed until the user explicitly confirms.
+
+## Write Rules
+
+On confirmation:
+
+1. Write confirmed scenarios to `requirement/vN/business-analysis.md` (requirements list + scenario list sections)
+2. **Do not update `ledger.md`** — ledger is batch-updated during version archival (Phase 3.6), not during scenario confirmation
+
+## Deprecation Handling
+
+When a scenario is deprecated (user explicitly requests removal):
+
+1. Delete the entry from `requirement/ledger.md`
+2. Delete the entry detail from the version's `business-analysis.md`
+3. Update `doc/active-registry/active-items.md` to reflect the current active set
+
+## Status Lifecycle
+
+Only two states exist:
+
+| State | Meaning |
+|---|---|
+| 🔵 pending | Drafted, awaiting QA-1 pass and user confirmation |
+| ✅ confirmed | User confirmed, written to business-analysis.md |
+
+No other states. Scenarios transition from 🔵 to ✅ only via Step 4 user confirmation.

package/skills/ce-brainstorm/references/evidence-chain-validation.md

@@ -0,0 +1,114 @@
+# Evidence Chain Validation — Phase 3.6 + QA-4 + Version Archiving
+
+This reference covers three connected operations after PRD generation: QA-4 quality check, bidirectional evidence chain validation, and version archiving. They execute in strict sequence: QA-4 → validation → archive.
+
+## QA-4: PRD Quality Checker (prd-quality-checker)
+
+**Trigger:** PRD document written (Phase 3 complete), before Phase 3.6 validation.
+**Route:** PASS → enter Phase 3.6; FAIL → return to Phase 3 to fix PRD.
+
+| ID | Category | Check | Severity |
+|----|----------|-------|----------|
+| C1 | Completeness | PRD §2 includes a business process overview table (L1–L4)? | Error |
+| C2 | Completeness | PRD §3 includes a flowchart + activity table for each confirmed process? | Error |
+| C3 | Completeness | Every feature in PRD §7 carries REQ-xxx + SC-xxx + BP-xxx triple-ID linkage? | Error |
+| C4 | Completeness | PRD §8 feature modules organized by process (BP-xxx grouping)? | Error |
+| C5 | Consistency | PRD §2 process overview table matches business-analysis.md process list? | Error |
+| C6 | Consistency | PRD §3 process descriptions match business-analysis.md process details? | Error |
+| C7 | Metadata | PRD frontmatter complete (title / project_name / iteration_version / date / prd_template)? | Warning |
+| C8 | Format | §8.4 feature extraction preserves original requirements detail (not over-summarized)? | Warning |
+
+**Verdict rule:** All Error-level checks pass → PASS. Any Error fails → FAIL. Warnings are reported but do not block.
+
+## Phase 3.6: Bidirectional Validation
+
+**Trigger:** QA-4 verdict = PASS.
+**Nature:** Automatic validation + user confirmation.
+
+### Inputs
+
+- `requirement/vN/prd.md` — the generated PRD
+- `requirement/ledger.md` — the master requirements ledger
+
+### Five Validation Dimensions
+
+**V1 — Scenario Coverage Completeness**
+Every scenario marked ✅ in the ledger must have functional coverage in PRD §7/§8. Check: for each ledger SC-xxx row with status ✅, find at least one PRD §7 feature referencing that SC-xxx ID.
+
+**V2 — Process Coverage Completeness**
+Every process marked ✅ in the ledger must appear in PRD §3. Check: for each ledger BP-xxx row with status ✅, find a corresponding PRD §3 section describing that process.
+
+**V3 — Step-to-Function Mapping**
+Each step of each confirmed process must map to a PRD §7 feature. Check: for every BP-xxx step listed in the ledger, find a PRD §7 feature whose triple-ID includes that BP-xxx and a matching step description.
+
+**V4 — Function Traceability Completeness**
+Every PRD §7 feature must carry a valid REQ-xxx + SC-xxx + BP-xxx triple. Check: parse each feature's ID block; verify each ID resolves to an existing ledger row. Flag orphan IDs or missing links.
+
+**V5 — Process Description Consistency**
+PRD §3 process descriptions must be consistent with business-analysis.md. Check: compare process name, step count, step names, and actor assignments between the two documents. Semantic equivalence is sufficient; verbatim match is not required.
+
+### Validation Verdict and Routing
+
+| Verdict | Condition | Next Step |
+|---------|-----------|-----------|
+| PASS | V1–V5 all pass | Proceed to version archiving, then Phase 4 |
+| CONDITIONAL_PASS | Failures in V1–V5 are explicitly marked "defer this iteration" by user | User annotates exempt items with justification → proceed to archiving |
+| FAIL | Unresolvable gaps remain | Return to Phase 3 to fix PRD, or return to Phase 1.5/1.6 to supplement requirements |
+
+## Version Archiving
+
+**Trigger:** Phase 3.6 verdict = PASS or CONDITIONAL_PASS.
+**Tier:** All tiers.
+**Nature:** Atomic, automated, no user interaction.
+
+### Pre-Checks (all must hold)
+
+1. Current-version business-analysis.md: all REQ status = ✅
+2. Current-version business-analysis.md: all SC status = ✅
+3. Current-version business-analysis.md: all BP status = ✅
+4. Phase 3.6 verdict = PASS or CONDITIONAL_PASS
+
+### Processing Steps
+
+**Step 1 — Ledger batch write/refresh**
+
+For every item in the current version's business-analysis.md:
+
+- New item → append a row to ledger.md
+- Modified item → refresh the existing row's `last_modified_version` and `directory` fields
+- Reverse references → refresh the `linked_processes` field in scenario/requirement ledger rows
+
+**Step 2 — Append archive record**
+
+Append one row to ledger.md's "Version Archive" section:
+
+| archive_version | archive_date | included_requirements | included_scenarios | included_processes | prd_path | status |
+
+**Step 3 — Mark business-analysis.md archived**
+
+Set frontmatter field `archived: true` in the current version's business-analysis.md.
+
+**Step 4 — Update active registry**
+
+Update `doc/active-registry/active-items.md` to reflect the newly archived items and retire any superseded entries.
+
+### Outputs
+
+- `requirement/ledger.md` — batch update complete
+- `requirement/vN/business-analysis.md` — archived flag set
+- `doc/active-registry/active-items.md` — updated
+
+### Exit
+
+Archiving complete → ready to enter `ce-plan` (development phase).
+
+## Compound Interest Archive Sync
+
+When archiving completes, the compound interest (复利) system should also update:
+
+1. Append a row to the ledger's "Release Records" table
+2. Fill the `release_version` field on relevant items
+3. Update PRD frontmatter metadata (mark published version)
+4. Item statuses remain unchanged (stay ✅ confirmed)
+
+This reference documents the trigger relationship only. Compound interest automation is owned by the `ce-compound` skill.