@xulthekl/team-flow 0.36.4 → 0.38.0

package/skills/release-archivist/SKILL.md

@@ -46,9 +46,11 @@ Compare contract batches against actual diff. Every SHALL/MUST must have impleme
 
 If `test-matrix.md` exists:
 1. **Statistics**: total cases / implemented / passed
-2. **Candidate Coverage Ledger audit**: any `decision=deferred` without reasonable reason?
-3. **Complexity tier check**: cases per module meet minimum (trivial≥3 / medium≥5 / complex≥7)?
-4. **Verdict**:
+2. **E2E 层豁免（v0.38.0）**：`test_tier=e2e` 的 case 从 coverage 分母豁免，单列统计 `e2e cases: implemented N/M（经 Step 5b 验证）`——E2E 证据由 Step 5b 对账，不参与本步骤 100%/90% 判定
+3. **Candidate Coverage Ledger audit**: any `decision=deferred` without reasonable reason?
+4. **Complexity tier check**: cases per module meet minimum (trivial≥3 / medium≥5 / complex≥7)?（E2E case 不参与模块用例数下限判定）
+5. **分母为 0 兜底（v0.38.0）**：纯 e2e change（无 unit/integration case，分母为 0）时，本步骤以 Step 5b E2E 验证结果为准，不判 FAIL（E2E 不替代低层级测试，但边界场景不卡死）
+6. **Verdict**:
    - Matrix coverage = 100% AND all cases pass → **PASS**
    - Matrix coverage ≥ 90% with reasonable deferred items → **CONDITIONAL (WARN)**
    - Matrix coverage < 90% OR unexplained gaps → **FAIL**
@@ -82,12 +84,20 @@ Check for files modified outside scope fence, new dependencies not in design. Un
 - CONDITIONAL → present WARNs, proceed only with user acceptance
 - PASS → proceed to final checks
 
-### Step 5b: E2E Verification (optional, v0.4)
-If an `e2e/` suite exists for the change, fold its report into verification (see design spec ch.16):
+### Step 5b: E2E Verification (conditional, v0.38.0 起由"存在 e2e/ 套件"改为"矩阵含 E2E case"触发)
+
+检测 `test-matrix.md` 是否含 `test_tier=e2e` 的 case：
+1. **无 E2E case** → 跳过（本步骤不执行）
+2. **有 E2E case 且已有 e2e 报告**（`docs/statistics/YYYY-MM-DD-e2e-report.md` 存在）→ 折进验证（见下）
+3. **有 E2E case 且无 e2e 报告** → **AskUserQuestion 阻塞确认**："test-matrix 含 {N} 个 E2E case，是否执行 E2E 测试？"
+   - **是** → 引导执行 `/e2e`（e2e skill：AC 提取 → Playwright 脚本 → 执行 → 报告 `docs/statistics/YYYY-MM-DD-e2e-report.md`），报告产生后回填本步骤验证
+   - **否** → 记录 E2E skip + 理由（如环境不具备/本期不做），报告行 `| E2E | SKIP | [reason] |`（不 FAIL）
+
+有 E2E 报告时的验证逻辑（4 级判定与门禁内联于此；design spec ch.16 仅概述）:
 - Read `docs/statistics/YYYY-MM-DD-e2e-report.md`: AC coverage / four-dimension coverage (EX/ST/BND) / type distribution / uncovered list / failure root-cause (test issue vs implementation issue).
 - **4-level artifact verification** (L1 existence / L2 substance / L3 wiring / L4 dataflow → VERIFIED/HOLLOW/ORPHANED/STUB/MISSING): compare `architecture-design` outputs (API/DB design docs) against actual code; STUB/MISSING = BLOCKER, HOLLOW/ORPHANED = WARNING.
 - **Graded gate**: prototype-phase AC≥80% (HP required, EX/ST/BND non-blocking if absent); integration-phase AC≥95% / EX≥80% / ST≥90% / BND≥75% (AC/EX = BLOCKER, ST/BND = WARNING).
-- Add a report row: `| E2E | PASS/FAIL/WARN | [coverage summary] |`.
+- Add a report row: `| E2E | PASS/FAIL/WARN/SKIP | [coverage summary or skip reason] |`.
 - Note: `ce-proof` is the Proof markdown editor — unrelated to verification; do NOT route E2E there.
 
 ## Final Checks
@@ -203,6 +213,15 @@ tf solutions capture \
 
 This check is advisory — skip silently if no learnable moments are detected.
 
+### 阶段产物同步门禁点（v0.37.0 §68.2 G5）
+
+回写链（arch-merge → prototype-sync → test-merge → compound promotion）全部完成后、`tf state transition closing` 之前，**阻塞确认**（AskUserQuestion）是否同步 change 实施结果（团队协作：落地结果是团队最需要看的内容）：
+- **A 提交并推送**：`tf publish --changes <change-dir> --push`
+- **B 仅提交不推送**：`tf publish --changes <change-dir>`（arch-merge/test-merge 已自动 commit，此步补 push）
+- **C 暂不同步**：继续 closing，后续可补
+
+同步对象：实施代码 `changes/<change-dir>/` + arch-merge 回写（docs/architecture/）+ test-ledger（docs/test-ledger/）。**原型独立仓库场景**：若本 change 有 UX 增量回写原型，push 对应 `prd-vN` 分支（`tf prototype branch <prd-vN>` 确认/创建 worktree）。
+
 ### Worktree Deisolation (v0.35.0) — advisory
 
 After compound promotion, check if worktree isolation exists for this change:

package/skills/spec-writer/SKILL.md

@@ -11,15 +11,19 @@ Create or refine planning artifacts when the change has moved beyond exploration
 
 Read `.team-flow.yaml` (especially `dp_0_decisions`, `dp_0_confirmed`) and any existing planning artifacts. If `dp_0_confirmed` is not `true`, stop and route back to `workflow-start` for DP-0.
 
-### Global Prototype Reading (v0.5)
+### Global Prototype Reading (v0.5, v0.37.0 版本化)
 
-Before generating artifacts, check if a global prototype exists:
-1. Read `prototype/flow.md` if it exists — this defines page navigation and user flows
-2. List `prototype/pages/` directory — these are the UI contract pages
-3. Read `prototype/design-system.md` if it exists — component and token definitions
-4. Store as UI contract context for design.md and tasks.md generation
+Before generating artifacts, **resolve the PRD version and locate the prototype worktree**:
+1. **版本推导（v0.37.0 §68.5）**：读 `change-brief.md` 的 `upstream_plan_ref: prd/vN/plan.md`（无 brief 时从 change 目录名 `v{N}-` 前缀推导）→ PRD 版本 vN
+2. **原型定位**：原型为独立仓库（有远程），版本 worktree = `<workspace>/.worktrees/prd-vN/prototype/`（该 worktree 不存在时回退 `<workspace>/prototype/` 并提示"原型应位于版本 worktree，`tf prototype branch <prd-vN>` 创建"）
+3. Read `prototype/flow.md` if it exists — this defines page navigation and user flows
+4. List `prototype/pages/` directory — these are the UI contract pages
+5. Read `prototype/design-system.md` if it exists — component and token definitions
+6. Store as UI contract context for design.md and tasks.md generation
 
-If `prototype/` does not exist or is empty, skip silently — not all projects have prototypes.
+If no prototype exists or it is empty, skip silently — not all projects have prototypes.
+
+**制品引用约定（v0.37.0 §68.5）**：design.md / tasks.md 中引用原型保留 `prototype/<rel>` 相对写法（可读性），但 `## UI Contract` / `**Prototype:**` 段必须**声明本 change 所属 PRD 版本 vN + 原型 worktree 路径**——实施阶段（build-executor）据此定位同一份原型，避免指向主干旧版本或空目录。
 
 ### Solutions Index (v0.5)
 
@@ -88,7 +92,7 @@ Every requirement must be testable. Use SHALL or MUST. Every requirement must ha
 
 Optional structured AC tags under a Scenario are supported for E2E extraction (v0.4, design spec ch.16): `##### Exception:` (→ EX AC, ×2), `##### State:` (→ ST AC, ×2), `##### Boundary:` (→ BND AC, ×1). These are **OPTIONAL** — omitting them does NOT fail validation. The `e2e` skill applies dimension-conditional gating (absent dimension = N/A, not 0%) plus keyword fallback (error/invalid/fail/边界), so no spec is forced to add tags.
 
-Optional test-dimension tags under a Scenario are supported for test-matrix extraction (v0.12 §44.1): `##### Unit:` (→ unit test hints: equivalence classes, boundary values), `##### Integration:` (→ integration test hints: cross-module, transaction boundaries). These are **OPTIONAL** — omitting them does NOT fail validation. The `contract-builder` extracts matrix skeletons from these tags when present, but does not require them.
+Optional test-dimension tags under a Scenario are supported for test-matrix extraction (v0.12 §44.1): `##### Unit:` (→ unit test hints: equivalence classes, boundary values), `##### Integration:` (→ integration test hints: cross-module, transaction boundaries), `##### E2E:` (→ e2e test hints: UI interaction / cross-layer flows; v0.38.0, test_tier=e2e). These are **OPTIONAL** — omitting them does NOT fail validation. The `contract-builder` extracts matrix skeletons from these tags when present, but does not require them.
 
 ### design.md
 Must have: Context (current state, constraints, stakeholders), Goals, Decisions (Choice + Rationale + Alternatives considered), Risks And Trade-Offs.

package/skills/test-strategy/SKILL.md

@@ -42,7 +42,8 @@ user-invocable: false
 
 - unit（test_tier=unit）：70-80% 的 case
 - integration（test_tier=integration）：≤30% 的 case
-- e2e：由 e2e skill 独立覆盖，不计入本矩阵
+- e2e（test_tier=e2e，v0.38.0）：含 **UI 交互/跨层链路**的 AC（如上下分栏联动、导出端到端、权限 403 端到端）必须显式评估 E2E 必要性——**纳入 E2E case 或记录排除理由**（不静默跳过）。E2E case 沿用标准 12 列格式，`test_tier=e2e`、case_id 用 `{Module}-e2e-{scene}-{NNN}`（3 连字符 + 数字结尾，满足复利台账计数）、mock 列填 `-`。
+- **金字塔分母 = unit + integration**（e2e 不计入金字塔配比，避免稀释 unit 占比判定）。
 
 ## 4. 对抗验证三招（矩阵生成后必检）
 

package/skills/test-strategy/references/design-methods-detail.md

@@ -179,5 +179,6 @@ CANCELLED ←──────────────┘ (仅 PAID 前可取
 | service_social, repository_h2 | integration |
 | rabbitmq_social, redis_social | integration |
 | external_api_stub, test_infrastructure | integration |
+| playwright_prototype, playwright_integration（v0.38.0） | e2e |
 
 **用途**：test_tier 用于统计和 CI 分级；test_kind 用于路由到正确的编写模板。

package/skills/test-strategy/references/test-quality-rules.md

@@ -226,6 +226,7 @@ class UserServiceCreateUserTest { ... }
 
 **检查**：
 - case 声明的 `test_tier` 与实际测试文件不符（如 unit case 写到了集成测试文件）
+- `test_tier=e2e` 的 case 合法落点是 `e2e/` 目录（Playwright spec，v0.38.0）——落在普通单元/集成测试文件里算 mismatch
 
 ### 12. evidence-not-in-method
 

package/skills/workflow-orchestrator/references/s2-prd-prototype-loop.md

@@ -82,6 +82,15 @@ PRD草稿生成后：
 
 设置 `frozen_downstream`（见 state-model.md「双层冻结」）。冻结后，**迭代内变更不升版**，在 vN 内修订 + 记录决策/变更履历。
 
+### 4.5 阶段产物同步门禁点（v0.37.0 §68.2 G1）
+
+S2 冻结后，**阻塞确认**（AskUserQuestion）是否同步阶段产物（团队协作：PRD+原型是需求讨论基线）：
+- **A 提交并推送**：`tf publish --prd --push`；原型为独立仓库时先 `tf prototype branch <prd-vN>` 确认/创建版本 worktree（迭代完成 push `prd-vN` 分支供团队查看者 `tf prototype branch <prd-vN>` 一键拉取）
+- **B 仅提交不推送**：`tf publish --prd`
+- **C 暂不同步**：继续 S3，后续可补
+
+同步对象：`prd/vN/` + 原型（push `prd-vN` 分支）+ `.team-flow/`（orchestrator.yaml / registry.yaml）。
+
 ### 5. 复利捕获
 
 检测可复利时刻（需求矛盾、原型返工、自动评审发现不一致并修正等）。每次自动评审发现不一致并修正后触发：
@@ -97,8 +106,8 @@ tf solutions capture --phase prd --domain <domain> --type pitfall --severity <se
 
 ## 原型自动评审（§17.10）
 
-**实现形式**：独立 `prototype-reviewer` agent（只读审查员，对齐 code-reviewer 模式）。
-- tools: Read, Bash, Grep, Glob（**无 Write**，报告写在 final response，编排层落盘）
+**实现形式**：独立 `prototype-reviewer` agent（对齐 code-reviewer 模式）。
+- tools: Read, Bash, Grep, Glob, Write（直接写审查报告文件）
 - 独立上下文运行，未参与 PRD/原型产出（规避锚定效应）
 - 两阶段检查：Pre-check（Bash 结构化预检，D1/D4 机械化）+ Deep-check（LLM 六维度语义对比，D2/D3/D5/D6 标注为「建议级，误报可被人工推翻」）
 

package/skills/workflow-orchestrator/references/s4-split-validate.md

@@ -137,6 +137,15 @@ Change C1 已就绪，运行 /workflow-start 进入变更级流程。
 执行顺序建议：C1 → (C2 ∥ C3) → C4（C2/C3 可并行）
 ```
 
+### 5.5 阶段产物同步门禁点（v0.37.0 §68.2 G3）
+
+S4 分发完成（orchestrator 结束）后，**阻塞确认**（AskUserQuestion）是否同步阶段产物（团队协作：成员领取任务的前提）：
+- **A 提交并推送**：`tf publish --changes --push`
+- **B 仅提交不推送**：`tf publish --changes`
+- **C 暂不同步**：结束编排，后续可补
+
+同步对象：`changes/*/`（脚手架 + change-brief.md）+ `.team-flow/`（change_dag / orchestrator.yaml）= 任务分发（成员领取）。
+
 ## 完成条件
 
 - change-split-auditor 审计 verdict = PASS（必选门禁已通过，含 v0.9 D5 拆分维度合规）

package/skills/workflow-start/SKILL.md

@@ -78,7 +78,7 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 > **⛔ 串行约束（v0.30.0）**：四步严格串行。**修复子代理（architecture-design）完成前 MUST NOT dispatch 审查子代理（architecture-reviewer）**——并行会使审查跑在修复之前、误报"全部未修复"FAIL（来源：workflow-feedback 2026-08-01）。并行白名单：仅多个独立 change 的工作可并行；修复→审查、设计→审查必须串行。
 
 1. **Dispatch**: `architecture-design` as sub-agent（**输入含 `docs/architecture/iterations/<vN>/architecture.md` 产品级架构快照**，v0.36.0——变更级只引用产品级聚合注册表，不重定义）→ returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
-2. **Auto-review** (decision=required 时触发): 校验产物文件存在且非空 → dispatch `architecture-reviewer` sub-agent（**记录子代理 ID**）→ FAIL 则通过 **SendMessage 恢复原 architecture-design 子代理**修正（≤3 轮 + 收敛检测，不收敛转人工）→ 报告落盘 `changes/<name>/architecture/auto-review.md`
+2. **Auto-review** (decision=required 时触发): 校验产物文件存在且非空 → dispatch `architecture-reviewer` sub-agent（**记录子代理 ID**，agent 会直接写审查报告到 `changes/<name>/architecture/auto-review.md`）→ FAIL 则通过 **SendMessage 恢复原 architecture-design 子代理**修正（≤3 轮 + 收敛检测，不收敛转人工）
 3. **Reasonableness check + state write**: PASS/PASS_WITH_WARNINGS → write `arch_design_decision` + `arch_review_*` to yaml; skipped + brief 含架构关键词 → BLOCK; required + artifacts 缺失 → BLOCK; required + auto-review FAIL → BLOCK
 4. **DP-A 用户确认门（v0.29.0 §37）**: 输出架构决策摘要 → AskUserQuestion 确认 → 需要调整时**必须通过 SendMessage 恢复原子代理**修改（禁止主代理直接修改，禁止启动新子代理）→ 修改后 SendMessage 恢复原 reviewer 重新 auto-review → 回到本步骤重新确认。含项目规范变更提示（advisory）。详见 `references/routing-rules.md`「Step 4: DP-A」
 
@@ -93,6 +93,15 @@ Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts
 ### Route to build-executor (dispatch sub-agent)
 Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK. **v0.13 §49 门禁前移**：该 guard 含 `test-matrix-ready` 维度——full 模式非存量 change 必须"带着矩阵开工"（矩阵存在非空 OR 显式 skip 附理由）；FAIL 时回 bridging 让 contract-builder 补矩阵，或按指引显式 skip，禁止绕过。
 
+### 阶段产物同步门禁点（v0.37.0 §68.2 G4）
+
+契约批准（DP-3）后、进入实施（DP-4）前，**阻塞确认**（AskUserQuestion）是否同步 change 规划制品（团队协作：契约是实施授权）：
+- **A 提交并推送**：`tf publish --changes <change-dir> --push`
+- **B 仅提交不推送**：`tf publish --changes <change-dir>`
+- **C 暂不同步**：直接进入实施，后续可补
+
+同步对象：change 规划制品 4+1（proposal / specs / design / tasks / execution-contract）+ `architecture/`。
+
 ### Route to bug-investigator
 Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.