@michaelxwb/code-flow 0.5.1 → 0.5.2

package/src/core/code-flow/scripts/cf_stop_hook.py

@@ -29,6 +29,11 @@ from cf_core import (
 
 TOTAL_BUDGET_SECONDS = 30.0
 _BRACE_RE = re.compile(r"\{([^{}]+)\}")
+_TASK_SECTION_RE = re.compile(
+    r"(?ms)^## (TASK-\d+):.*?(?=^## TASK-\d+:|\Z)"
+)
+_SCENARIO_RE = re.compile(r"\b[SEB]-\d+\b")
+_UNVERIFIED_RE = re.compile(r"\b(?:planned|pending|tbd)\b", re.IGNORECASE)
 
 
 def expand_braces(pattern: str) -> list:
@@ -83,6 +88,79 @@ def session_edited_files(project_root: str, sid: str) -> list:
     return files
 
 
+def _is_active_task_file(rel_path: str) -> bool:
+    path = normalize_path(rel_path)
+    if not path.startswith(".code-flow/tasks/") or "/archived/" in path:
+        return False
+    return path.endswith(".md") and not path.endswith((".design.md", ".prd.md"))
+
+
+def _subsection(section: str, heading: str) -> str:
+    match = re.search(
+        rf"(?ms)^### {re.escape(heading)}\s*$\n(.*?)(?=^### |^## |\Z)",
+        section,
+    )
+    return match.group(1) if match else ""
+
+
+def _acceptance_gap(task_id: str, section: str, coverage: str) -> str:
+    status = re.search(r"(?m)^- \*\*Status\*\*: ([^\n]+)", section)
+    if not status or status.group(1).strip() != "done":
+        return ""
+    refs_match = re.search(r"(?m)^- \*\*Acceptance-Refs\*\*: ([^\n]+)", section)
+    if not refs_match:
+        return f"{task_id} 缺少 Acceptance-Refs"
+    refs = refs_match.group(1).strip()
+    if refs.upper().startswith("N/A"):
+        return ""
+    scenarios = sorted(set(_SCENARIO_RE.findall(refs)))
+    if not scenarios:
+        return f"{task_id} Acceptance-Refs 未引用 S/E/B 场景"
+    contract = _subsection(section, "Acceptance Contract")
+    evidence = _subsection(section, "Acceptance Evidence")
+    if not contract or not evidence:
+        return f"{task_id} 缺少 Acceptance Contract 或 Acceptance Evidence"
+    if _UNVERIFIED_RE.search(contract) or _UNVERIFIED_RE.search(evidence):
+        return f"{task_id} 验收契约仍有 planned/pending/TBD"
+    for scenario in scenarios:
+        contract_ok = any(scenario in line and "verified" in line.lower()
+                          for line in contract.splitlines())
+        evidence_ok = any(scenario in line and "verified" in line.lower()
+                          for line in evidence.splitlines())
+        coverage_ok = any(scenario in line and "verified" in line.lower()
+                          for line in coverage.splitlines())
+        if not contract_ok or not evidence_ok or not coverage_ok:
+            return f"{task_id} 的 {scenario} 未在覆盖表、契约和证据中全部 verified"
+    return ""
+
+
+def task_acceptance_failures(project_root: str, files: list) -> list:
+    """Check new-format task files; legacy tasks without coverage are ignored."""
+    failures = []
+    for rel_path in files:
+        if not _is_active_task_file(rel_path):
+            continue
+        path = os.path.join(project_root, normalize_path(rel_path))
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                text = f.read()
+        except OSError as exc:
+            _log(f"cf_stop_hook task read failed: {exc}")
+            continue
+        if "## Acceptance Coverage" not in text:
+            continue
+        coverage = text.split("## Acceptance Coverage", 1)[1].split("## TASK-", 1)[0]
+        for match in _TASK_SECTION_RE.finditer(text):
+            detail = _acceptance_gap(match.group(1), match.group(0), coverage)
+            if detail:
+                failures.append({
+                    "name": "任务验收契约",
+                    "on_fail": "补齐设计场景的测试映射与执行证据后再完成任务",
+                    "detail": detail,
+                })
+    return failures
+
+
 def run_validators(
     project_root: str, validators: list, files: list, sid: str,
     total_budget: float = TOTAL_BUDGET_SECONDS,
@@ -144,7 +222,7 @@ def run_validators(
 
 
 def _reason_text(failures: list, truncated: bool) -> str:
-    lines = ["收尾校验未通过（cf-stop，FEAT-03）："]
+    lines = ["收尾校验未通过（cf-stop）："]
     for item in failures:
         lines.append(f"✗ {item['name']}：{item['on_fail']}")
         if item["detail"]:
@@ -174,12 +252,14 @@ def main() -> None:
         files = session_edited_files(project_root, sid)
         if not files:
             return
+        acceptance_failures = task_acceptance_failures(project_root, files)
         validators = load_validators(project_root)
-        if not validators:
-            return  # E-05: 无 validation.yml 静默
-        failures, truncated = run_validators(project_root, validators, files, sid)
+        failures, truncated = run_validators(
+            project_root, validators, files, sid
+        ) if validators else ([], False)
+        failures = acceptance_failures + failures
         if not failures:
-            return  # 全过静默（S-05）
+            return  # 全过或无 validation.yml 且无验收缺口时静默
         payload = {"decision": "block", "reason": _reason_text(failures, truncated)}
         sys.stdout.write(json.dumps(payload, ensure_ascii=False))
     except Exception as exc:

package/src/core/code-flow/specs/shared/design/design-frontend.md

@@ -90,19 +90,19 @@
 
 ### 2.4 验收条件 [必填]
 
-> 交互层面的可验证场景，写到可转 e2e / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。
+> 交互层面的可验证场景，写到可转 E2E / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。测试层级只能填 `unit` / `integration` / `E2E` / `manual`；跨路由、服务请求、状态更新和最终 UI 的用户流程必须标为 `E2E`。关键真实边界列出不得 mock 的浏览器、路由、状态或服务边界。
 
 **正常场景**
 
-| 场景ID | 功能ID | 优先级 | 操作步骤 | 预期 UI 结果 |
-|--------|--------|--------|---------|-------------|
-| S-01 | FEAT-01 | P0 | 1. <操作> | <可见结果> |
+| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期 UI 结果 |
+|--------|--------|--------|---------|-------------|---------|-------------|
+| S-01 | FEAT-01 | P0 | E2E | Browser → Router → Service → UI | 1. <操作> | <可见结果> |
 
 **异常场景**
 
-| 场景ID | 功能ID | 触发条件 | UI 表现 |
-|--------|--------|---------|---------|
-| E-01 | FEAT-01 | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
+| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | UI 表现 |
+|--------|--------|---------|-------------|---------|---------|
+| E-01 | FEAT-01 | integration | Service → UI | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
 
 **非功能指标** [按需]
 
@@ -227,9 +227,9 @@
 
 ## 4. 风险与依赖 [按需]
 
-| 风险ID | 描述 | 影响 | 应对 |
-|--------|------|------|------|
-| | | | |
+| 风险ID | 描述 | 影响 | 应对 | 验证场景 |
+|--------|------|------|------|---------|
+| | | | | S-/E-/B- 或手动验证理由 |
 
 ---
 

package/src/core/code-flow/specs/shared/design/design-full.md

@@ -133,32 +133,34 @@
 
 #### 2.5.1 业务规则与约束
 
-| ID | 类型 | 描述 |
-|----|------|------|
-| RULE-01 | 业务规则 | |
-| RULE-02 | 系统约束 | 单次批量导入上限≤10000条 |
+| ID | 类型 | 描述 | 验证场景 |
+|----|------|------|---------|
+| RULE-01 | 业务规则 | | S-01 |
+| RULE-02 | 系统约束 | 单次批量导入上限≤10000条 | B-01 |
 
 #### 2.5.2 功能验收场景
 
-> 场景写到可转自动化测试断言的粒度（明确前置、输入、可观测输出）。场景 ID（S-/E-/B-）即测试用例来源，§6 追溯矩阵的 TC-XXX 直接引用这些场景 ID。
+> 场景写到可转自动化测试断言的粒度（明确前置、输入、可观测输出）。场景 ID（S-/E-/B-）即测试用例来源，§6 追溯矩阵直接引用这些场景 ID。
+>
+> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
 
 **正常场景**
 
-| 场景ID | 功能ID | 优先级 | 前置条件 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|---------|---------|
-| S-01 | FEAT-01 | P0 | | | |
+| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 前置条件 | 操作步骤 | 预期结果 |
+|--------|--------|--------|---------|-------------|---------|---------|---------|
+| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | | | |
 
 **异常场景**
 
-| 场景ID | 功能ID | 触发条件 | 系统行为 | 用户感知 |
-|--------|--------|---------|---------|---------|
-| E-01 | FEAT-01 | | | |
+| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 | 用户感知 |
+|--------|--------|---------|-------------|---------|---------|---------|
+| E-01 | FEAT-01 | integration | Service → Store | | | |
 
 **边界场景** [按需]
 
-| 场景ID | 字段/条件 | 边界值 | 预期行为 |
-|--------|----------|--------|---------|
-| B-01 | | | |
+| 场景ID | 测试层级 | 关键真实边界 | 字段/条件 | 边界值 | 预期行为 |
+|--------|---------|-------------|----------|--------|---------|
+| B-01 | unit | 校验函数 | | | |
 
 #### 2.5.3 非功能指标 [按需]
 
@@ -386,9 +388,9 @@ flowchart TD
 
 **风险 / 失效应对**（默认轻量表）
 
-| 风险ID | 失效模式 | 影响 | 应对措施 |
-|--------|---------|------|---------|
-| RISK-01 | | | |
+| 风险ID | 失效模式 | 影响 | 应对措施 | 验证场景 |
+|--------|---------|------|---------|---------|
+| RISK-01 | | | | E-01 |
 
 > 仅安全关键 / 高并发 / 强一致系统才升级为 FMEA：追加 S/O/D（1-10）与 RPN=S×O×D 三列，RPN≥200 上线前必须解决。普通功能用上表即可，不要为打分而打分。
 
@@ -457,19 +459,19 @@ flowchart TD
 
 ### 5.2 风险识别
 
-| 风险ID | 类型 | 描述 | 概率 | 影响 | 应对措施 |
-|--------|------|------|------|------|---------|
-| | | | | | |
+| 风险ID | 类型 | 描述 | 概率 | 影响 | 应对措施 | 验证场景 |
+|--------|------|------|------|------|---------|---------|
+| | | | | | | S-/E-/B- 或手动验证理由 |
 
 ---
 
 ## 6. 需求追溯矩阵
 
-| 用户故事 | 功能ID | 接口ID | 测试用例ID | 状态 |
-|---------|--------|--------|-----------|------|
-| US-01 | FEAT-01 | API-01 | TC-001 | ✅ |
+| 用户故事 | 功能ID | 接口ID | 测试用例ID | 测试层级 | 状态 |
+|---------|--------|--------|-----------|---------|------|
+| US-01 | FEAT-01 | API-01 | S-01 | E2E | 待实现 |
 
-> 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；测试用例 ID 列引用 §2.5.2 的场景 ID（S-/E-/B-），不要另造编号。
+> 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；测试用例 ID 列引用 §2.5.2 的场景 ID（S-/E-/B-），不要另造编号。RULE 与高影响 RISK 必须映射到场景；无法自动化时写明手动验证原因，不得留空。
 
 ---
 

package/src/core/code-flow/specs/shared/design/design-lite.md

@@ -109,18 +109,20 @@
 #### 2.4.1 功能验收场景
 
 > 每个 P0/P1 FEAT 至少 1 条正常 + 1 条异常场景；"操作步骤/预期结果"写到可直接转为自动化测试断言的粒度（明确输入与可观测输出）。场景 ID（S-/E-/B-）即测试用例编号，供 plan 拆解引用。
+>
+> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
 
 **正常场景**
 
-| 场景ID | 功能ID | 优先级 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|---------|
-| S-01 | FEAT-01 | P0 | 1. <步骤><br>2. <步骤> | <结果> |
+| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期结果 |
+|--------|--------|--------|---------|-------------|---------|---------|
+| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | 1. <步骤><br>2. <步骤> | <结果> |
 
 **异常场景**
 
-| 场景ID | 功能ID | 触发条件 | 系统行为 |
-|--------|--------|---------|---------|
-| E-01 | FEAT-01 | | |
+| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 |
+|--------|--------|---------|-------------|---------|---------|
+| E-01 | FEAT-01 | integration | Service → Store | | |
 
 #### 2.4.2 非功能指标 [按需]
 
@@ -274,9 +276,9 @@ flowchart TD
 
 ### 4.2 风险识别
 
-| 风险ID | 描述 | 影响 | 应对措施 |
-|--------|------|------|---------|
-| | | | |
+| 风险ID | 描述 | 影响 | 应对措施 | 验证场景 |
+|--------|------|------|---------|---------|
+| | | | | S-/E-/B- 或手动验证理由 |
 
 ---