@chenmk/superflow 0.5.13 → 0.5.14

package/assets/scripts/superflow-test-report-lint.py

@@ -14,6 +14,7 @@ mechanically:
 from __future__ import annotations
 
 import argparse
+import json
 import re
 import subprocess
 import sys
@@ -99,6 +100,13 @@ EXTERNAL_EVIDENCE_RE = re.compile(
     re.I,
 )
 CASE_ID_RE = re.compile(r"\bT\d+(?:\.\d+)+\b")
+CASE_EVIDENCE_HEADER = re.compile(
+    r"^\|\s*(?:用例\s*ID|Case\s*ID)\s*\|\s*(?:入口\s*ID|Entry\s*ID)\s*\|"
+    r"\s*(?:验收级别|Acceptance\s*level)\s*\|\s*(?:结果|Result)\s*\|"
+    r"\s*(?:证据|Evidence)(?:路径|\s*path)?\s*\|$",
+    re.I,
+)
+CASE_RESULTS = {"PASS", "FAIL", "BLOCKED", "PARTIAL"}
 OLD_PHRASES = (
     "不会按周期边界拆分子切片",
     "1 秒空窗落入下一周期对账无实质影响",
@@ -253,6 +261,69 @@ def lint_against_tests_contract(report_path: Path, report_text: str, tests_path:
     return issues
 
 
+def lint_case_evidence(report_path: Path, report_text: str, review_path: Path) -> list[Issue]:
+    """Check the frozen R/E/C index against per-case execution receipts."""
+    issues: list[Issue] = []
+    try:
+        review = json.loads(review_path.read_text(encoding="utf-8"))
+        coverage = review["coverage"]
+        if coverage["schemaVersion"] != "superflow.review-coverage.v1":
+            raise ValueError("unsupported coverage schema")
+        cases = {case["id"]: case for case in coverage["cases"]}
+        decisions = coverage["decisions"]
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        return [Issue("FAIL", report_path, 0, f"入口评审凭证无法读取：{error}")]
+
+    required = {
+        case_id
+        for decision in decisions
+        if decision.get("disposition") != "EXCLUDED"
+        for case_id in decision.get("caseIds", [])
+    }
+    lines = report_text.splitlines()
+    header_at = next(
+        (i for i, line in enumerate(lines) if CASE_EVIDENCE_HEADER.fullmatch(line.strip())),
+        None,
+    )
+    if header_at is None:
+        return [Issue("FAIL", report_path, 0, "缺少逐用例执行证据表；不能用汇总通过数代替 R/E/C 回填")]
+
+    receipts: dict[str, tuple[str, str, str, str]] = {}
+    for index, line in enumerate(lines[header_at + 2 :], start=header_at + 3):
+        if not line.startswith("|"):
+            break
+        columns = [column.strip() for column in line.strip().strip("|").split("|")]
+        if len(columns) != 5:
+            issues.append(Issue("FAIL", report_path, index, "逐用例执行证据表必须有五列"))
+            continue
+        case_id, entry_id, level, result, evidence = columns
+        if case_id in receipts:
+            issues.append(Issue("FAIL", report_path, index, f"用例 {case_id} 重复回填"))
+        receipts[case_id] = (entry_id, level, result.upper(), evidence)
+
+    for case_id in sorted(required):
+        if case_id not in receipts:
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 缺少逐项执行结果"))
+            continue
+        entry_id, level, result, evidence = receipts[case_id]
+        case = cases.get(case_id)
+        if case is None or entry_id != case.get("entryId") or level != case.get("level"):
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的入口或验收级别与冻结合同不一致"))
+        if result not in CASE_RESULTS or not evidence or evidence.lower() in {"pending", "todo", "待补"}:
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 缺少有效结果或证据位置"))
+        elif result == "PASS" and not re.match(r"^https?://", evidence, re.I):
+            evidence_file = Path(evidence.split("#", 1)[0])
+            if not evidence_file.is_absolute():
+                evidence_file = report_path.parent / evidence_file
+            if not evidence_file.is_file():
+                issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的通过证据文件不存在：{evidence}"))
+        if result != "PASS" and re.search(r"验证结果\s*[:：]\s*PASS|Verification Result\s*[:：]\s*PASS", report_text, re.I):
+            issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 为 {result}，报告不能声明整体验证 PASS"))
+    for case_id in receipts.keys() - required:
+        issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 未在冻结入口评审中要求执行"))
+    return issues
+
+
 def infer_tests_path(report: Path) -> Path | None:
     direct = report.parent / "tests.md"
     if direct.exists():
@@ -268,7 +339,8 @@ def infer_tests_path(report: Path) -> Path | None:
     return None
 
 
-def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None) -> list[Issue]:
+def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None,
+                review_path: Path | None = None) -> list[Issue]:
     issues: list[Issue] = []
     text = path.read_text(encoding="utf-8", errors="replace")
     lines = text.splitlines()
@@ -278,6 +350,8 @@ def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None) -
     blocked = bool(BLOCKED_RE.search(text))
     passed_or_partial = bool(PASS_WORDS.search(text) or re.search(r"Partially verified|部分验证", text, re.I))
     issues.extend(lint_against_tests_contract(path, text, tests_path or infer_tests_path(path)))
+    if review_path is not None:
+        issues.extend(lint_case_evidence(path, text, review_path))
 
     if db_backed and passed_or_partial and not blocked:
         if not TABLE_REVERSE_HEADER_RE.search(text):
@@ -395,6 +469,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(description="Lint SuperBridge Flow test-report evidence")
     parser.add_argument("reports", nargs="+")
     parser.add_argument("--tests", default="")
+    parser.add_argument("--review", default="")
     parser.add_argument("--repo-root", default="")
     parser.add_argument("--warn-only", action="store_true")
     args = parser.parse_args()
@@ -407,7 +482,10 @@ def main() -> int:
             continue
         repo = Path(args.repo_root).resolve() if args.repo_root else repo_root_for(path)
         tests_path = Path(args.tests).resolve() if args.tests else None
-        all_issues.extend(lint_report(path, repo, tests_path))
+        if tests_path is not None and not tests_path.exists():
+            all_issues.append(Issue("FAIL", path, 0, f"显式指定的 tests.md 不存在：{tests_path}"))
+        review_path = Path(args.review).resolve() if args.review else None
+        all_issues.extend(lint_report(path, repo, tests_path, review_path))
 
     printable = []
     for issue in all_issues:

package/assets/skills/superflow-docs/SKILL.md

@@ -380,6 +380,18 @@ DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
   `用例ID | 需求/Scenario | 层级L1/L2/L3/L4 | 前置数据 | 操作步骤 |
   自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
   test-report证据位置`.
+- For cross-page management or database-backed display changes, reconcile the
+  frontend action/list inventory with real Controller, Service, exact Mapper
+  statement and table anchors before freezing tasks. Put the confirmed chain
+  and entry ID in `source-code-audit.md` and reuse it in `design.md`, `tasks.md`
+  and `tests.md`. A similarly named query is not evidence for the page route.
+  Include every visible mutation button, such as enable/disable, as an entry
+  even when the original task list omitted it.
+- For a returned persisted field, `tests.md` must freeze at least one non-null
+  fixture and an allowed historical-NULL fixture separately. Assert API and DB
+  values for the same record ID, then browser rendering where a page is in
+  scope. Key-presence, HTTP 200, empty-page and NULL-only assertions cannot
+  close the non-null data path. Name the exact query/command and evidence file.
 - 对 L3/L4 的输入校验、协议拒绝或异常分支，`tests.md` 还必须冻结真实注入载荷及其到达
   目标解析/校验分支的证据；仅断言同一个 HTTP 状态码不算覆盖。原始畸形 JSON、错误
   Content-Type、越权身份或非法字段必须按真实线协议发送，并同时断言无副作用。

package/assets/skills/superflow-pipeline/SKILL.md

@@ -41,6 +41,9 @@ CLI 命令：
 停止，不创建托管 Task；已有用户评审通过的 change/Prompt 时原路径冻结；只有边界清晰的
 口头小需求才直接进入 minimal/standard。若口头需求存在会改变实现方向的 API、数据、
 并发、跨仓或 owner 决策，先进入澄清/文档流程，不能把这一判断交给 Runner 正则或 Executor。
+多页面、跨前后端、数据库字段横向改造要求闭环交付时，按完整 SDD 冻结真实入口、
+`tests.md` 和逐入口验收合同。仅有 OpenSpec `spec/design/tasks` 或通用冒烟报告，
+只能声明相应范围已实现/验证，不得称为完整 SDD 验收。
 
 ```bash
 superflow pipeline "<implementation-prompt 路径、change 目录或简单任务>" --managed --project "<项目根目录>" \

package/assets/skills/superflow-pipeline/references/document-review-coverage.md

@@ -24,6 +24,14 @@
    同页面不同角色的分支用不同入口 ID；不得只测试开发者选中的新接口。
 5. 验收同时断言返回、最终状态和禁止的副作用。只读/纯函数场景也要给出明确
    无持久化变更的理由，不能留空。browser 入口必须有 browser 验收，API 测试只能补充。
+6. 横向页面/字段改造先从前端路由、列表列和可点击动作建立页面入口清单，再从后端
+   Controller、Mapper statement、全部写入方反向建立清单。逐项对账后才生成 tasks/tests；
+   相似方法名不得作为调用关系证据。每个列表记录实际页面请求、Controller、Service、
+   精确 Mapper statement、返回 DTO 与表；每个管理按钮记录实际 mutation API 和写入点。
+   未定位或两份清单不一致的入口标记待调查，不得以总数相等替代逐项核验。
+7. 数据库字段展示用例必须分别覆盖一个非空记录与允许的历史 NULL 记录。非空记录
+   用同一业务 ID 比较 API 字段与数据库真源值，并在浏览器核对展示；仅有字段键、HTTP
+   200、空列表或历史 NULL 不能证明字段链路正确。修改入口还要验证写后读及禁止的副作用。
 
 ## 凭证扩展
 
@@ -80,3 +88,13 @@ coding-ready 复检失败会写 BLOCKED 撤销旧 READY。
 验收阶段沿同一 R/E/C ID 在 `test-report.md` 回填实际角色、动作、请求路由、状态/
 副作用断言、原始日志路径及结果。主 Agent 对照原始来源和实际证据，不只看测试汇总。
 计划用例不是执行证据；API-only 不能报页面 E2E 成功。脚本未验证业务语义的部分不得宣称自动保证。
+完整 SDD 报告使用唯一的逐用例执行证据表，供现有 report lint 核对冻结索引：
+
+| 用例 ID | 入口 ID | 验收级别 | 结果 | 证据路径 |
+|---|---|---|---|---|
+| C1 | E1 | browser | PASS | logs/C1-trace.zip |
+
+结果只用 `PASS/FAIL/BLOCKED/PARTIAL`；证据路径指向实际命令输出、浏览器 trace、
+响应或数据库对账记录。PASS 的本地证据文件必须保留到验收并可读取；远端证据可用
+HTTP(S) 链接。阻塞项在报告正文写明原因。表格仅证明用例逐项回填，不能证明
+证据内容正确。任何非 PASS 用例存在时，不得声明整体验证 PASS。

package/assets/skills/superflow-pipeline/references/test-execution-template.md

@@ -71,6 +71,17 @@ mvn test -Dtest=UserServiceTest
 
 ## 4.1 真实测试数据与证据
 
+完整 SDD 变更还需按 `document-review.json` 的 R/E/C 索引逐项回填，不得用总通过数
+代替单个入口的结果。下表供 `superflow-test-report-lint.py --review` 校验：
+
+| 用例 ID | 入口 ID | 验收级别 | 结果 | 证据路径 |
+|---|---|---|---|---|
+| C1 | E1 | browser | PASS | logs/C1-trace.zip |
+
+`PASS/FAIL/BLOCKED/PARTIAL` 之外的值无效；非 PASS 项在正文说明原因。
+数据库字段展示要分别记录非空数据按同一 ID 的 API/DB 值对账、历史 NULL 结果和
+真实浏览器展示。API 键存在、静态前端配置与浏览器显示分别记录证据等级。
+
 | 用例 ID | 真实参数 | 参数来源 | 自动化命令 | 证据等级 | 执行证据 | 结论 |
 |---------|----------|----------|------------|----------|----------|------|
 | TC-001 | parkCode=____ | 前端请求 / 用户提供 / DB查询 / Mock | curl/Newman/pytest/RestAssured | Mock only / 测试端点 / 真实入口 | 响应 + DB + 日志 | Passed / Blocked / Partial |

package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh

@@ -87,15 +87,21 @@ project_root_for_change() {
 
 require_test_report_lint() {
   local report="$CHANGE_DIR/test-report.md"
-  local root lint output
+  local root lint output review
+  local -a lint_args
   root="$(project_root_for_change)"
+  review="$CHANGE_DIR/.sdd/reviews/document-review.json"
+  lint_args=(--tests "$CHANGE_DIR/tests.md")
+  if [[ -f "$review" ]]; then
+    lint_args+=(--review "$review")
+  fi
 
   for lint in \
     "$root/.codex/hooks/superflow-test-report-lint.py" \
     "$HOME/.codex/hooks/superflow-test-report-lint.py"; do
     if [[ -x "$lint" ]]; then
       output="$(mktemp)"
-      if ! "$lint" --tests "$CHANGE_DIR/tests.md" "$report" >"$output" 2>&1; then
+      if ! "$lint" "${lint_args[@]}" "$report" >"$output" 2>&1; then
         issues+=("superflow-test-report-lint failed: $(tr '\n' ' ' < "$output" | sed -E 's/[[:space:]]+/ /g')")
       fi
       rm -f "$output"

package/assets/skills/superflow-verify/SKILL.md

@@ -34,6 +34,8 @@ unverifiable claims separate rather than giving them a guessed severity.
 完整 workflow 验收必须读取[需求×真实入口评审](../superflow-pipeline/references/document-review-coverage.md)。
 沿 R/E/C ID 在现有 test-report 回填实际角色、页面动作、请求路由、最终状态与禁止副作用
 的原始证据。独立对照原始来源及实际调用方；API-only 不得冒充 browser E2E，计划不等于执行。
+横向字段改造还要复核页面请求命中的精确 Mapper statement，并查看非空记录的同 ID
+API/DB 值对照与浏览器显示。历史 NULL、字段键存在和静态列配置各自只能支持较弱结论。
 
 Verification is a phase, not a final sentence. Use this skill after
 implementation work claims completion and before archive or delivery.
@@ -140,7 +142,8 @@ Before pass:
    DB/log/API evidence, handoff hash, and phase state.
 2. `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` passes when the
    report involves integration evidence.
-3. `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> <test-report.md>`
+3. `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> --review
+   <.sdd/reviews/document-review.json> <test-report.md>`
    passes. If `tests.md` declares L3/L4, real-entry, third-party, device,
    database, log, or dev-tool evidence, mock-only/unit-only reports are hard
    failures unless the report is explicitly `Blocked` or `Partially verified`

package/assets/skills-en/superflow-docs/SKILL.md

@@ -376,6 +376,18 @@ Use references only as needed:
   `Case ID | Requirement/scenario | Level L1/L2/L3/L4 | Precondition data | Steps |
   Automation command | Response assertion | DB assertion | Log assertion | RED expected failure | GREEN expected pass |
   test-report evidence location`.
+- For cross-page management or database-backed display changes, reconcile the
+  frontend action/list inventory with real Controller, Service, exact Mapper
+  statement and table anchors before freezing tasks. Put the confirmed chain
+  and entry ID in `source-code-audit.md` and reuse it in `design.md`, `tasks.md`
+  and `tests.md`. A similarly named query is not evidence for the page route.
+  Include every visible mutation button, such as enable/disable, as an entry
+  even when the original task list omitted it.
+- For a returned persisted field, `tests.md` must freeze at least one non-null
+  fixture and an allowed historical-NULL fixture separately. Assert API and DB
+  values for the same record ID, then browser rendering where a page is in
+  scope. Key-presence, HTTP 200, empty-page and NULL-only assertions cannot
+  close the non-null data path. Name the exact query/command and evidence file.
 - For L3/L4 input validation, protocol rejection, and exceptional branches,
   `tests.md` also freezes the real injected payload and evidence that it reaches
   the intended parser or validation branch; matching the same HTTP status alone

package/assets/skills-en/superflow-pipeline/SKILL.md

@@ -61,6 +61,10 @@ user-approved change/prompt is frozen from its original path. Only a bounded
 verbal request enters minimal or standard directly. Direction-changing API,
 data, concurrency, cross-repository, or owner choices return to
 clarification/documents; Runner regexes and Executor improvisation do not decide them.
+For cross-page, cross-stack or database-field changes requesting closed delivery,
+use full SDD to freeze real entries, `tests.md` and per-entry acceptance. A raw
+OpenSpec `spec/design/tasks` set or generic smoke report supports only its
+actually verified scope, not a full SDD acceptance claim.
 
 ```bash
 superflow pipeline "<implementation prompt, change directory, or direct task>" --managed --project "<project root>" \

package/assets/skills-en/superflow-pipeline/references/document-review-coverage.md

@@ -26,6 +26,16 @@ investigate source-resolvable questions autonomously.
 5. Assert response, final state and forbidden effects. For read-only/pure-function work explain
    why no persistent change applies; do not leave blanks. Browser paths require browser acceptance;
    API checks can supplement, not replace them.
+6. For cross-page or field changes, inventory frontend routes, list columns and clickable actions
+   independently from backend Controllers, exact Mapper statements and all writers. Reconcile both
+   inventories before writing tasks/tests. Similar method names are not call-chain evidence. For
+   every list record page request, Controller, Service, exact Mapper statement, response DTO and
+   table; for every management button record its mutation API and write point. Investigate missing
+   or conflicting entries instead of treating matching totals as proof.
+7. A database-backed display case needs both a non-null fixture and a separate allowed historical
+   NULL case. Compare API fields with authoritative DB values for the same business ID, then check
+   browser rendering. Field keys, HTTP 200, empty lists and historical NULL alone are insufficient.
+   Mutation cases also check write-then-read behavior and forbidden side effects.
 
 ## Receipt extension
 
@@ -87,3 +97,13 @@ During verification, reuse R/E/C IDs in `test-report.md`, recording actual actor
 request route, state/forbidden-effect assertions, raw evidence paths and outcomes. The Host
 compares them to original sources, not only a test summary. Planned cases are not execution
 evidence; API-only results cannot claim browser E2E. Do not claim automatic semantic assurance.
+Full SDD reports use one per-case execution evidence table for the existing report linter:
+
+| Case ID | Entry ID | Acceptance level | Result | Evidence path |
+|---|---|---|---|---|
+| C1 | E1 | browser | PASS | logs/C1-trace.zip |
+
+Results are `PASS/FAIL/BLOCKED/PARTIAL`. Evidence points to actual command output, browser trace,
+response or DB reconciliation. Retain readable local evidence files for PASS; HTTP(S) links may
+identify remote evidence. Explain blockers in the report body. This table proves case-level
+accounting only; the Host must inspect evidence contents. Any non-PASS case prevents an overall PASS.

package/assets/skills-en/superflow-pipeline/references/test-execution-template.md

@@ -55,6 +55,18 @@ Archive Readiness: PASS / BLOCKED
 
 Required for `verify_mode: full`:
 
+For full SDD changes, fill every R/E/C case from `document-review.json` in one
+execution table checked by `superflow-test-report-lint.py --review`:
+
+| Case ID | Entry ID | Acceptance level | Result | Evidence path |
+|---|---|---|---|---|
+| C1 | E1 | browser | PASS | logs/C1-trace.zip |
+
+Use only `PASS/FAIL/BLOCKED/PARTIAL`; explain non-PASS results in the report.
+For database-backed display fields, record same-ID API/DB values on non-null
+data, historical NULL separately, and real browser rendering. Distinguish
+field-key checks, static frontend inspection and browser evidence.
+
 - Test environment:
 - Branch/commit/build number or image:
 - Base URL:

package/assets/skills-en/superflow-pipeline/scripts/superflow-guard.sh

@@ -87,15 +87,21 @@ project_root_for_change() {
 
 require_test_report_lint() {
   local report="$CHANGE_DIR/test-report.md"
-  local root lint output
+  local root lint output review
+  local -a lint_args
   root="$(project_root_for_change)"
+  review="$CHANGE_DIR/.sdd/reviews/document-review.json"
+  lint_args=(--tests "$CHANGE_DIR/tests.md")
+  if [[ -f "$review" ]]; then
+    lint_args+=(--review "$review")
+  fi
 
   for lint in \
     "$root/.codex/hooks/superflow-test-report-lint.py" \
     "$HOME/.codex/hooks/superflow-test-report-lint.py"; do
     if [[ -x "$lint" ]]; then
       output="$(mktemp)"
-      if ! "$lint" --tests "$CHANGE_DIR/tests.md" "$report" >"$output" 2>&1; then
+      if ! "$lint" "${lint_args[@]}" "$report" >"$output" 2>&1; then
         issues+=("superflow-test-report-lint failed: $(tr '\n' ' ' < "$output" | sed -E 's/[[:space:]]+/ /g')")
       fi
       rm -f "$output"

package/assets/skills-en/superflow-verify/SKILL.md

@@ -40,6 +40,10 @@ For full workflow acceptance, read [requirement × real-entry review](../superfl
 Reuse R/E/C IDs in the existing test-report with actual actors, page actions, request routes,
 final state and forbidden-effect evidence. Independently compare originals and actual callers;
 API-only is not browser E2E, and planned cases are not execution evidence.
+For cross-page field changes, recheck the exact Mapper statement reached by each
+page request and inspect same-ID API/DB comparisons on non-null records plus
+browser rendering. Historical NULL, field keys and static column configuration
+support narrower claims only.
 
 Verification is a phase, not a final sentence. Use this skill after
 implementation work claims completion and before archive or delivery.
@@ -146,7 +150,8 @@ Before pass:
    DB/log/API evidence, handoff hash, and phase state.
 2. `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` passes when the
    report involves integration evidence.
-3. `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> <test-report.md>`
+3. `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> --review
+   <.sdd/reviews/document-review.json> <test-report.md>`
    passes. If `tests.md` declares L3/L4, real-entry, third-party, device,
    database, log, or dev-tool evidence, mock-only/unit-only reports are hard
    failures unless the report is explicitly `Blocked` or `Partially verified`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenmk/superflow",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "description": "SuperBridge Flow workflow CLI for Claude Code and Codex",
   "license": "MIT",
   "type": "module",