@chenmk/superflow 0.4.0 → 0.5.0

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

@@ -322,6 +322,103 @@ change_has_field_status_risk() {
     "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
 }
 
+change_has_database_change() {
+  if grep -Eiq '^[[:space:]]*database:[[:space:]]*false([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 1
+  fi
+  if grep -Eiq '^[[:space:]]*database:[[:space:]]*true([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 0
+  fi
+  grep -RIEiq \
+    'database_change[[:space:]]*:[[:space:]]*true|数据库变更.{0,8}(是|需要|包含)|ALTER[[:space:]]+TABLE|CREATE[[:space:]]+TABLE|ADD[[:space:]]+(COLUMN|INDEX|KEY|CONSTRAINT)|(^|[^不未无])新增.{0,12}(表|字段|索引|约束)|(^|[^不未无])(历史数据|初始化数据).{0,12}(迁移|回填)|schema[ -]migration|database[ -]migration|add.{0,12}(table|column|index|constraint)' \
+    "$CHANGE_DIR/proposal.md" \
+    "$CHANGE_DIR/api.md" \
+    "$CHANGE_DIR/design.md" \
+    "$CHANGE_DIR/tasks.md" \
+    "$CHANGE_DIR/database-contract.md" \
+    "$CHANGE_DIR/spec.md" \
+    "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
+}
+
+require_frozen_release_sql() {
+  local release_sql="$CHANGE_DIR/release-sql.md"
+  local output
+
+  require_file release-sql.md
+  [[ -f "$release_sql" ]] || return 0
+
+  output="$(mktemp)"
+  if ! python3 - "$release_sql" >"$output" 2>&1 <<'PY'
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+text = path.read_text(encoding="utf-8")
+errors = []
+
+front_match = re.match(r"\A---\n(.*?)\n---(?:\n|\Z)", text, re.S)
+front = front_match.group(1) if front_match else ""
+if not front_match:
+    errors.append("front matter is missing")
+
+def field(name):
+    match = re.search(rf"(?m)^{re.escape(name)}:\s*(.*?)\s*$", front)
+    return match.group(1).strip().strip('"\'') if match else ""
+
+if field("database_change").lower() != "true":
+    errors.append("database_change must be true")
+
+target = field("target_sql_path")
+if not target or not target.lower().endswith(".sql"):
+    errors.append("target_sql_path must be an exact .sql path")
+if re.search(r"[<>{}]|testN|version|待定|pending", target, re.I):
+    errors.append("target_sql_path contains a placeholder")
+
+if field("copy_policy").lower() != "verbatim":
+    errors.append("copy_policy must be verbatim")
+
+declared_hash = field("sql_sha256").lower()
+if not re.fullmatch(r"[0-9a-f]{64}", declared_hash):
+    errors.append("sql_sha256 must be a 64-character lowercase SHA-256")
+
+blocks = re.findall(r"```sql[^\n]*\n(.*?)\n```", text, re.S | re.I)
+if len(blocks) != 1:
+    errors.append("release-sql.md must contain exactly one sql code block")
+else:
+    payload = blocks[0].replace("\r\n", "\n").replace("\r", "\n").rstrip("\n") + "\n"
+    actual_hash = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    if declared_hash and actual_hash != declared_hash:
+        errors.append(
+            f"sql_sha256 mismatch: declared={declared_hash} actual={actual_hash}"
+        )
+    executable = re.sub(r"/\*.*?\*/|--[^\n]*", "", payload, flags=re.S)
+    if not re.search(
+        r"\b(CREATE|ALTER|DROP|INSERT|UPDATE|DELETE|MERGE|TRUNCATE|CALL)\b",
+        executable,
+        re.I,
+    ):
+        errors.append("sql block has no executable schema/data change statement")
+    if not re.search(r"\b(SELECT|SHOW|CALL)\b", executable, re.I):
+        errors.append("sql block has no executable verification statement")
+
+if errors:
+    print("; ".join(errors))
+    sys.exit(1)
+PY
+  then
+    issues+=("frozen release SQL invalid: $(tr '\n' ' ' < "$output" | sed -E 's/[[:space:]]+/ /g')")
+  fi
+  rm -f "$output"
+
+  require_grep 'release-sql\.md' design.md "frozen release SQL design reference"
+  require_grep 'release-sql\.md' tasks.md "frozen release SQL task reference"
+  require_grep 'release-sql\.md' sdd-quality-gate.md "frozen release SQL quality-gate reference"
+  require_grep '原样复制|verbatim' tasks.md "verbatim SQL copy task"
+  require_grep '原样复制|verbatim' sdd-quality-gate.md "verbatim SQL copy quality gate"
+}
+
 change_has_external_enum_risk() {
   grep -RIEiq \
     'BEM|payOrigin|payMode|支付来源|支付方式|财务口径|第三方枚举|第三方字段|third[- ]party enum|source system|SDK.*枚举|枚举.*SDK' \
@@ -352,6 +449,12 @@ change_all_docs_without_complexity_budget() {
 }
 
 change_has_external_config_risk() {
+  if grep -Eiq '^[[:space:]]*external_config:[[:space:]]*false([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 1
+  fi
+  if grep -Eiq '^[[:space:]]*external_config:[[:space:]]*true([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 0
+  fi
   local content
   content="$(change_contract_docs_without_complexity_budget)"
   grep -Eiq \
@@ -360,6 +463,12 @@ change_has_external_config_risk() {
 }
 
 change_has_concurrency_idempotency_risk() {
+  if grep -Eiq '^[[:space:]]*concurrency:[[:space:]]*false([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 1
+  fi
+  if grep -Eiq '^[[:space:]]*concurrency:[[:space:]]*true([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 0
+  fi
   grep -RIEiq \
     '并发|批量下发|批量开通|批量续费|重复提交|重复回调|重复消费|重复下发|幂等|竞态|原子占用|concurren|idempoten|race condition|duplicate (request|callback|consumption|delivery)|atomic claim' \
     "$CHANGE_DIR/proposal.md" \
@@ -371,6 +480,12 @@ change_has_concurrency_idempotency_risk() {
 }
 
 change_has_money_precision_risk() {
+  if grep -Eiq '^[[:space:]]*money:[[:space:]]*false([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 1
+  fi
+  if grep -Eiq '^[[:space:]]*money:[[:space:]]*true([[:space:]]*#.*)?$' "$CHANGE_DIR/.openspec.yaml" 2>/dev/null; then
+    return 0
+  fi
   grep -RIEiq \
     '金额|费用|价格|优惠|折扣|抵扣|退款|分账|支付|发票|余额|电费|服务费|套餐结算|比例分摊|明细分配|尾差|精度|舍入|(^|[^[:alnum:]_])(amount|fee|fees|price|discount|deduction|refund|payment|invoice|balance|proration|allocation|reconciliation|rounding)([^[:alnum:]_]|$)|revenue sharing|profit sharing|split payment|serviceFee|chargeFee|totalAmount|actualAmount|payAmount|refundAmount|discountAmount|invoiceAmount|balanceAmount' \
     "$CHANGE_DIR/proposal.md" \
@@ -381,6 +496,53 @@ change_has_money_precision_risk() {
     "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
 }
 
+change_has_source_fact_risk() {
+  grep -RIEiq \
+    '现有|现行|遗留|数据库|数据表|表关系|Mapper|XML|跨仓|跨服务|真实入口|小程序|H5|existing|current behavior|legacy|database|table relationship|cross[- ](repo|service)|crosses services|real entry|mini[- ]program' \
+    "$CHANGE_DIR/proposal.md" \
+    "$CHANGE_DIR/api.md" \
+    "$CHANGE_DIR/design.md" \
+    "$CHANGE_DIR/tests.md" \
+    "$CHANGE_DIR/spec.md" \
+    "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
+}
+
+change_has_cardinality_conflict_signal() {
+  grep -RIEiq \
+    'List[<（(]|orderIds|batchInsert|批量插入|一对多|one[- ]to[- ]many|关系表' \
+    "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
+}
+
+require_source_fact_audit() {
+  require_file source-code-audit.md
+  require_grep '源码事实冻结卡|Source Fact Freeze Card' source-code-audit.md "source fact freeze card"
+  require_grep '业务结论|Business conclusion' source-code-audit.md "source fact business conclusion"
+  require_grep 'understand.*定位|understand.*locator' source-code-audit.md "understand-anything locator evidence"
+  require_grep '数据模型|Data model' source-code-audit.md "source fact data model"
+  require_grep '所有写入方|All writers' source-code-audit.md "all writers inventory"
+  require_grep '真实用户入口|Real user entr' source-code-audit.md "real user entry"
+  require_grep '当前调用方|Current callers' source-code-audit.md "current callers"
+  require_grep '遗留冲突|Legacy conflict' source-code-audit.md "legacy conflict"
+  require_grep 'DB.*(必查|核查|跳过|未执行|reason)|数据库.*(必查|核查|跳过|未执行|原因)|DB (check|required|skip|reason)' source-code-audit.md "DB check or skip reason"
+  require_grep '结论等级|Conclusion level' source-code-audit.md "conclusion level"
+  require_grep 'owner.*(决策|decision)|决策.*owner' source-code-audit.md "owner decision boundary"
+  require_grep 'current|现行入口' source-code-audit.md "current evidence classification"
+  require_grep 'legacy|遗留入口' source-code-audit.md "legacy evidence classification"
+  require_grep 'unmounted|无前端调用' source-code-audit.md "unmounted evidence classification"
+  require_grep 'data-model-only|仅数据模型可表达' source-code-audit.md "data-model-only evidence classification"
+  require_grep 'owner-confirmed|owner 已确认' source-code-audit.md "owner-confirmed evidence classification"
+  require_grep 'blocked|阻塞' source-code-audit.md "blocked evidence classification"
+  require_grep '(证据分类|Evidence classifications).*(current|现行).*(legacy|遗留).*(unmounted|无前端调用).*(data-model-only|仅数据模型可表达).*(owner-confirmed|owner 已确认).*(blocked|阻塞)' source-code-audit.md "complete evidence classification set"
+  require_grep '提问资格门禁|Question Eligibility Gate' source-code-audit.md "question eligibility gate"
+  require_grep '源码检索|Source search' source-code-audit.md "source search evidence"
+  require_grep 'Mapper.*SQL|SQL.*Mapper' source-code-audit.md "Mapper and SQL search evidence"
+  require_grep '前端.*小程序.*H5|Frontend.*mini[- ]program.*H5' source-code-audit.md "frontend mini-program H5 caller search"
+  require_grep 'sibling.*repo|兄弟仓|关联仓' source-code-audit.md "sibling repository search"
+  if change_has_cardinality_conflict_signal; then
+    require_grep '冲突审计|Conflict Audit' source-code-audit.md "cardinality conflict audit"
+  fi
+}
+
 change_has_fx_precision_risk() {
   grep -RIEiq \
     '汇率|换汇|外汇|币种转换|跨币种|兑换率|(^|[^[:alnum:]_])(exchange rate|fx rate|currency conversion|cross.currency|base currency|quote currency)([^[:alnum:]_]|$)' \
@@ -400,8 +562,10 @@ change_has_architecture_boundary_risk() {
     <<< "$content"
 }
 
-first_prompt_rel() {
-  find "$CHANGE_DIR" -path '*/prompt/*.md' -type f | head -n 1 | sed "s#^$CHANGE_DIR/##"
+prompt_rels() {
+  find "$CHANGE_DIR" -path '*/prompt/*.md' -type f -print \
+    | LC_ALL=C sort \
+    | sed "s#^$CHANGE_DIR/##"
 }
 
 require_any_prompt() {
@@ -411,7 +575,7 @@ require_any_prompt() {
 }
 
 require_prompt_set() {
-  local task_count prompt_count non_index_prompt_count
+  local task_count prompt_count non_index_prompt_count prompt_rel document
   require_file prompt/implementation.md
   task_count="$(grep -E '^[[:space:]]*-[[:space:]]+\[[ xX]\]' "$CHANGE_DIR/tasks.md" 2>/dev/null | wc -l | tr -d ' ')"
   prompt_count="$(find "$CHANGE_DIR/prompt" -maxdepth 1 -type f -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
@@ -422,9 +586,15 @@ require_prompt_set() {
   if [[ "$prompt_count" -eq 0 ]]; then
     issues+=("missing prompt/*.md files")
   fi
-  if [[ -f "$CHANGE_DIR/tasks.md" ]] && ! grep -Riq 'prompt/.*\.md' "$CHANGE_DIR/tasks.md" "$CHANGE_DIR/traceability-matrix.md" "$CHANGE_DIR/sdd-quality-gate.md" "$CHANGE_DIR/test-report.md" 2>/dev/null; then
-    issues+=("prompt files are not cross-linked from tasks/traceability/quality gate/test-report")
-  fi
+  for document in tasks.md traceability-matrix.md sdd-quality-gate.md test-report.md; do
+    [[ -f "$CHANGE_DIR/$document" ]] || continue
+    while IFS= read -r prompt_rel; do
+      if ! grep -Fq "]($prompt_rel)" "$CHANGE_DIR/$document" \
+        && ! grep -Fq "](./$prompt_rel)" "$CHANGE_DIR/$document"; then
+        issues+=("$document does not link $prompt_rel")
+      fi
+    done < <(prompt_rels)
+  done
 }
 
 require_external_enum_contract() {
@@ -571,11 +741,27 @@ case "$PHASE" in
     require_grep 'RED|红绿|GREEN' tests.md "RED/GREEN test contract"
     require_grep 'curl|Postman|Newman|pytest|RestAssured|自动化命令' tests.md "interface automation command"
     require_grep 'handoff_hash|sdd-context|上下文包|防漂移' sdd-quality-gate.md "handoff/context-drift gate"
+    if change_has_database_change; then
+      require_frozen_release_sql
+    fi
     workflow="$(state_get workflow)"
     if [[ "$workflow" == "full" ]]; then
+      require_file requirement-review.md
+      require_grep '^review_verdict:[[:space:]]*PASS[[:space:]]*$' requirement-review.md "requirement reverse review PASS verdict"
+      require_grep '^implementation_readiness:[[:space:]]*READY[[:space:]]*$' requirement-review.md "requirement review implementation readiness"
+      require_grep '^open_blockers:[[:space:]]*0[[:space:]]*$' requirement-review.md "requirement reverse review has no open blockers"
+      require_grep '^open_external_contracts:[[:space:]]*0[[:space:]]*$' requirement-review.md "requirement review has no open external contracts"
+      require_grep '^open_source_investigations:[[:space:]]*0[[:space:]]*$' requirement-review.md "requirement review has no open source investigations"
+      require_grep '^open_owner_decisions:[[:space:]]*0[[:space:]]*$' requirement-review.md "requirement review has no open owner decisions"
+      require_grep '闭环矩阵|Closure Matrix' requirement-review.md "requirement review closure matrix"
+      require_grep '评审发现|Review Findings' requirement-review.md "requirement review findings"
+      require_grep '未关闭阻塞项|Open Blockers' requirement-review.md "requirement review open blocker ledger"
       require_minimal_design_review design.md "complexity reduction review"
       require_grep '复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review' sdd-quality-gate.md "complexity reduction quality gate"
       require_minimal_design_pass sdd-quality-gate.md
+      if change_has_source_fact_risk; then
+        require_source_fact_audit
+      fi
     fi
     if change_has_external_enum_risk; then
       require_external_enum_contract api.md "external enum binding contract"
@@ -610,6 +796,9 @@ case "$PHASE" in
     require_handoff_current
     require_beta_handoff_structure
     require_hash_recorded
+    if change_has_database_change; then
+      require_frozen_release_sql
+    fi
     workflow="$(state_get workflow)"
     if [[ "$workflow" == "full" ]]; then
       require_minimal_design_review design.md "complexity reduction review"
@@ -652,11 +841,14 @@ case "$PHASE" in
     require_handoff_current
     require_beta_handoff_structure
     require_hash_recorded
+    if change_has_database_change; then
+      require_frozen_release_sql
+    fi
     require_any_prompt
     require_prompt_set
     require_grep 'OpenSpec/SDD|设计事实源|canonical|事实源' design.md "canonical source boundary"
-    prompt_rel="$(first_prompt_rel)"
-    if [[ -n "${prompt_rel:-}" ]]; then
+    while IFS= read -r prompt_rel; do
+      [[ -n "${prompt_rel:-}" ]] || continue
       require_grep 'Superpower 技术详设继承|Superpower 执行策略继承|technical_design|源码级 HOW' "$prompt_rel" "prompt Superpower strategy inheritance"
       technical_design_rel="$(state_get technical_design)"
       if [[ -n "${technical_design_rel:-}" && "$technical_design_rel" != "null" ]]; then
@@ -678,7 +870,11 @@ case "$PHASE" in
         fi
       fi
       require_grep '上下文防漂移|handoff_hash|sdd-context' "$prompt_rel" "prompt context drift inheritance"
-    fi
+      if change_has_database_change; then
+        require_grep 'release-sql\.md' "$prompt_rel" "prompt frozen release SQL reference"
+        require_grep '原样复制|verbatim|sql_sha256' "$prompt_rel" "prompt verbatim SQL copy contract"
+      fi
+    done < <(prompt_rels)
     require_state_value build_mode "build_mode"
     require_state_value isolation "isolation"
     require_state_value tdd_mode "tdd_mode"

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

@@ -244,10 +244,13 @@ sync_state() {
   "$state_sh" set "$CHANGE_DIR" context_compression "$context_compression"
   "$state_sh" set "$CHANGE_DIR" handoff_context .sdd/handoff/sdd-context.json
   "$state_sh" set "$CHANGE_DIR" handoff_hash "$context_hash"
-  technical_design_rel="$(
-    find "$CHANGE_DIR/docs/superpowers/specs" -maxdepth 1 -type f -name '*.md' 2>/dev/null \
-      | sort | head -n 1 | sed "s#^$CHANGE_DIR/##"
-  )"
+  technical_design_rel=""
+  if [[ -d "$CHANGE_DIR/docs/superpowers/specs" ]]; then
+    technical_design_rel="$(
+      find "$CHANGE_DIR/docs/superpowers/specs" -maxdepth 1 -type f -name '*.md' \
+        | sort | head -n 1 | sed "s#^$CHANGE_DIR/##"
+    )"
+  fi
   if [[ -n "$technical_design_rel" ]]; then
     "$state_sh" set "$CHANGE_DIR" technical_design "$technical_design_rel"
   fi

package/assets/skills/superflow-requirement-review/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: superflow-requirement-review
+description: 对已澄清或已形成 OpenSpec/SDD 草案的需求和设计执行源码驱动的反向评审，主动发现闭环缺口、事实冲突、遗漏场景、过度设计、欠设计、API/UI/DB/tests 漂移及不可验证合同，并推动整改和复审闭环。Use when the user asks for 需求评审、反向评审、挑战需求、找遗漏、查错误、检查可测性、评审设计是否走偏、检查过度设计，或要求在 Superflow docs/design/implementation 前做独立审查。
+---
+
+# Superflow Requirement Review
+
+对当前 OpenSpec change 进行独立、对抗式但基于证据的反向评审。评审不是旁路建议：
+阻塞级问题必须回写并修正文档，复审通过后才能离开 docs 阶段。
+
+## 边界
+
+- 在复杂需求完成逐功能澄清、形成可评审文档草案后使用。
+- 不替代 `superflow-clarify` 的 owner 决策确认，也不替代源码、Mapper/SQL、DB 和
+  真实调用方核查。
+- 不创建平行需求体系；产物必须落在当前 `openspec/changes/<change>/`。
+- 不只输出意见清单。发现成立的问题后，必须修正 canonical 文档并复审。
+- 不为了“解决遗漏”增加没有真实需求或复用证据的表、接口、服务、缓存和状态。
+
+## 必须读取
+
+按当前任务范围读取：
+
+- 原始需求索引：`source-ingestion.md`、`feature-inventory.md`、`feature-gates.md`
+- 合同：`proposal.md`、`api.md`、`specs/**/spec.md`、`design.md`
+- 证据：`source-code-audit.md`、`database-contract.md`、`release-sql.md`
+- 交付：`tasks.md`、`tests.md`、`traceability-matrix.md`、
+  `review-checklist.md`、`sdd-quality-gate.md`、`test-report.md`
+- 当前源码、Mapper/XML、真实前端/小程序/H5 调用方、sibling repo，以及必要的
+  只读数据库证据
+
+缺少某类文件时记录为评审发现，不得凭聊天记忆补结论。
+
+## 评审流程
+
+### 1. 冻结评审基线
+
+记录 change、当前 phase、需求来源、功能范围、handoff hash 和已确认/待确认决策。
+一次只评审一个已冻结功能；不得把下一功能的问题混入当前结论。
+
+### 2. 建立证据资格
+
+先完成平台影响面发现，再回到源码、Mapper/SQL、真实调用方和必要的只读 DB。
+understand-anything 只作定位。将证据标记为 `current`、`legacy`、`unmounted`、
+`data-model-only`、`owner-confirmed` 或 `blocked`。
+
+仓库和数据库能查明的事实不得转问用户。只有 owner 取舍才进入澄清，并且一次只问
+一个决策问题。
+
+所有未决项先按解决责任分类，禁止统一写成“外部待确认”：
+
+- `SOURCE_INVESTIGATION`：源码、依赖、配置、日志或只读数据库可以查明。评审者必须
+  继续调查，未查完不得退出评审，也不得转问用户。
+- `OWNER_DECISION`：存在两个以上成立方案，需要产品或业务 owner 取舍。返回
+  `superflow-clarify`，一次只问一个问题。
+- `EXTERNAL_CONTRACT`：第三方请求/响应、签名、幂等、枚举、回调或跨服务责任合同。
+  只要会改变 API、SQL、状态机、安全实现或测试断言，就属于实现阻塞项，必须取得
+  合同证据后才能 PASS；“已在文档标记 Blocked”不算关闭。
+- `EXECUTION_EVIDENCE`：已经冻结实现合同，仅等待部署、真实调用、迁移或运行证据。
+  可以留在 tests/test-report 阻塞交付，但不得伪装成合同未知项。
+
+### 3. 六向反查
+
+逐项从结果反推前提，不能只沿设计正向复述：
+
+1. **业务闭环**：输入、触发、前置条件、处理、输出、异常、恢复、取消/重复动作。
+2. **源码事实**：真实入口、全部写入方、读取/过滤方、遗留能力、跨仓消费者、DB样本。
+3. **合同一致性**：PRD/截图、UI、API、DTO/VO、DB、状态枚举、SQL、tests 和 tasks。
+4. **失败与边界**：越权、并发、幂等、超时、不确定结果、乱序回调、部分失败、脏数据。
+5. **复杂度减法**：重复字段、平行接口、无必要 Service、缓存/MQ/定时任务、推测性兼容。
+6. **可交付性**：每条需求是否有实现任务、RED/GREEN、真实入口、DB/log证据和验收口径。
+
+涉及数据库时必须使用 `superflow-table-impact-analysis`，或在不可用时按同等规则降级
+执行并记录原因。
+
+### 4. 记录发现
+
+创建或更新当前 change 的 `requirement-review.md`：
+
+```markdown
+---
+change: <change-name>
+review_verdict: BLOCKED
+implementation_readiness: BLOCKED
+open_blockers: <number>
+open_external_contracts: <number>
+open_source_investigations: <number>
+open_owner_decisions: <number>
+---
+
+# 需求反向评审
+
+## 评审基线
+- change：
+- phase：
+- 功能范围：
+- 来源与证据：
+- handoff hash：
+
+## 闭环矩阵
+| 功能点 | 输入/触发 | 处理 | 输出 | 异常 | 恢复/重复 | 证据 | 结论 |
+|---|---|---|---|---|---|---|---|
+
+## 评审发现
+| ID | 等级 | 维度 | 位置 | 问题 | 证据 | 影响 | 最小修正 | 状态 |
+|---|---|---|---|---|---|---|---|---|
+
+## 未关闭阻塞项
+| ID | 分类 | 影响的实现合同 | 解决责任 | 下一证据/问题 | 状态 |
+|---|---|---|---|---|---|
+
+## 过度设计与欠设计
+| 设计项 | 现有复用 | 必要性 | 删除/保留结论 | 证据 |
+|---|---|---|---|---|
+
+## 复审结论
+- BLOCKED / PASS
+- 未关闭发现：
+- 已修正文档：
+- 仍需 owner 决策：
+```
+
+等级只能使用：
+
+- `BLOCKER`：需求事实、API/DB/状态、安全、真实入口或验收合同错误，阻塞推进。
+- `IMPORTANT`：高概率造成遗漏、返工或不可测，必须在 docs 阶段修正。
+- `SUGGESTION`：不影响合同正确性的改进建议，可由 owner 决定。
+
+### 5. 整改
+
+每个成立的 `BLOCKER/IMPORTANT` 必须：
+
+1. 修正原始 canonical 文档，而不是只修改 `requirement-review.md`。
+2. 同步 API、design、spec、SQL、tasks、tests、traceability 和 quality gate 中受影响项。
+3. 记录“问题 → 修正文件 → 测试/证据”的闭环。
+4. 若修正改变 owner 已确认合同，停止并回到 `superflow-clarify`。
+
+### 6. 独立复审
+
+整改后重新从需求来源和源码证据检查，不以“文档已经修改”为通过依据。
+
+通过条件：
+
+- 所有 `BLOCKER/IMPORTANT` 已关闭并有文件与测试证据。
+- 没有未解释的 UI/API/DB/SQL/status/tests 漂移。
+- 复杂度减法结论成立，没有无证据的新抽象。
+- `SOURCE_INVESTIGATION` 已穷尽并回写证据，数量为0。
+- owner 决策均已记录，`OWNER_DECISION` 数量为0。
+- 会改变实现的 `EXTERNAL_CONTRACT` 已取得证据并冻结，数量为0；仅写成
+  `Blocked`、分配 owner 或列入任务不算关闭。
+- 剩余项只能是不会改变实现合同的 `EXECUTION_EVIDENCE`，并已进入测试/发布门禁。
+- `requirement-review.md` 结论为 `PASS`。
+- front matter 精确记录 `review_verdict: PASS`、`implementation_readiness: READY`、
+  `open_blockers: 0`、`open_external_contracts: 0`、
+  `open_source_investigations: 0` 和 `open_owner_decisions: 0`。
+
+### 7. 刷新门禁
+
+文档修正后刷新 handoff，并运行 docs guard 与 OpenSpec strict validate。将
+`requirement-review.md` 路径、复审结论和未关闭项同步到 `sdd-quality-gate.md` 与
+`test-report.md`。
+
+## 禁止项
+
+- 禁止只按文档文字评审而不核源码和真实入口。
+- 禁止把数据模型可表达能力当成当前产品行为。
+- 禁止用“字段非空、接口200、编译通过”替代业务语义正确。
+- 禁止为了覆盖边界而虚构默认值、fallback、状态或兼容层。
+- 禁止把评审结果落到其他流程目录，导致 OpenSpec change 无法追踪。
+- 禁止未关闭阻塞问题却将 docs/design 标为通过。
+- 禁止以“文档已记录”“已有 owner”“待联调”关闭会改变实现的外部合同。
+- 禁止 `review_verdict: PASS` 与 `implementation_readiness: BLOCKED` 并存。
+
+## Handoff
+
+评审通过后继续当前 Superflow 阶段；若发现 owner 决策缺失，返回
+`superflow-clarify`；若发现文档合同缺失，返回 `superflow-docs` 并在修正后再次执行
+本 skill。

package/assets/skills/superflow-requirement-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Superflow 需求反向评审"
+  short_description: "基于源码反查需求与设计缺口并推动整改复审闭环"
+  default_prompt: "使用 $superflow-requirement-review 对当前 OpenSpec 需求和设计执行反向评审并闭环整改。"

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

@@ -23,6 +23,21 @@ any full SDD document or implementation prompt is generated.
 - Do not freeze a feature from product text or understand-anything output alone
   when code impact is relevant. Current source, Mapper/XML, database samples,
   API contracts, or real consumer entry points must confirm the design.
+- For features that depend on existing behavior, table relationships, or call
+  chains, create a `source-code-audit.md` Source Fact Freeze Card before
+  freezing: `Business conclusion | understand-anything locator | Data model |
+  All writers | Real user entry | Current callers | Legacy conflict | DB check
+  required | Conclusion level | owner decision`. Treat understand-anything only
+  as a locator and confirm every conclusion in source, Mapper/SQL, current
+  callers, or read-only DB evidence.
+- Classify evidence as `current`, `legacy`, `unmounted`, `data-model-only`,
+  `owner-confirmed`, or `blocked`. If `List`, `orderIds`, `batchInsert`, or a
+  one-to-many relation exists while the real UI/mini-program/H5 submits one
+  item, add a Conflict Audit and do not infer current batch behavior.
+- Before asking the user, record a Question Eligibility Gate covering source,
+  Mapper/SQL, frontend/mini-program/H5 callers, sibling repositories, and the
+  DB check or skip reason. Do not ask the user for facts discoverable from the
+  repository or read-only data; ask only for owner-intent decisions.
 - When the feature depends on existing code relationships, field ownership,
   table joins, data permissions, status transitions, or upstream/downstream
   calls, verify the relationship before freezing with current evidence:
@@ -81,6 +96,8 @@ Create or update these files in the active OpenSpec change directory:
 - `ui-contract.md`: page fields, controls, buttons, list columns, dropdowns, API/DTO/DB mapping.
 - `gap-analysis.md`: UI/document/source gaps and over-design risks.
 - `spec-freeze-review.md`: freeze card for the current feature.
+- `source-code-audit.md`: source fact freeze card, evidence classifications,
+  conflict audit, and question eligibility gate.
 - Platform impact evidence in one of the above documents: discovery method,
   understand-anything index status when available, analyzed platform scope,
   impacted modules/interfaces/tables, regression risks, source/DB/API

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

@@ -21,6 +21,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 
 ## Preconditions
 
+- When the change modifies a database schema, index, constraint, seed data, or
+  historical data, `release-sql.md` must already contain the complete executable
+  release SQL, an exact target `.sql` path, `copy_policy: verbatim`, and a valid
+  `sql_sha256`. Source-level HOW design must not defer SQL design to an
+  implementation prompt.
+
 - `proposal.md`, `api.md`, `design.md`, `tasks.md`, `tests.md`,
   `traceability-matrix.md`, `sdd-quality-gate.md`, and `test-report.md` exist.
 - `.sdd/state.yaml` exists and is in `phase: design`. If still `docs`, run:
@@ -38,15 +44,21 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 
 1. Read `.sdd/handoff/sdd-context.md` plus original `api.md`, `design.md`,
    `tasks.md`, and `tests.md`.
-2. If design discussion is still evolving, maintain
+2. For a database change, verify `release-sql.md` before source-level HOW
+   design: one complete executable SQL block, exact destination, normalized
+   SHA-256, pre/post checks, and explicit verbatim-copy references in
+   `design.md`, `tasks.md`, and `sdd-quality-gate.md`. Any unresolved type,
+   default, index, migration rule, or target path returns to
+   `$superflow-docs`; it must not be deferred to `$superflow-implement`.
+3. If design discussion is still evolving, maintain
    `.sdd/handoff/brainstorm-summary.md` with confirmed, candidate, pending, and
    rejected items. Do not create final technical design from memory only.
-3. Use Superpowers `brainstorming` or equivalent deep design reasoning to
+4. Use Superpowers `brainstorming` or equivalent deep design reasoning to
    decide source-level HOW.
-4. Write:
+5. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-5. Complete `Minimal Design Review` before expanding source-level HOW. For
+6. Complete `Minimal Design Review` before expanding source-level HOW. For
    every new table, field, API, service/component, abstraction, cache,
    async/MQ/event flow, scheduled job, or compatibility layer, prove existing
    reuse options, necessity, and why the simplest direct implementation is
@@ -56,7 +68,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    premature caches, and async compensation without measured need. Record
    retained and removed counts; unresolved simpler alternatives keep the
    design blocked.
-6. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
+7. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
    callback, third-party, mini-program, gateway, or adapter changes, include
    `Architecture Boundary And Call Direction`. Prove owner module, call
    direction, existing entry/exit points, proposed entry/exit points, evidence
@@ -64,7 +76,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    adapter/protocol translator/device gateway into a business-entry
    orchestrator, stop and return to `$superflow-docs` unless the OpenSpec/SDD
    contract explicitly grants that ownership with approval evidence.
-7. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+8. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
    gateways, cloud services, or other external integrations, include
    `External Integration Configuration And Deployment Contract`. Inventory
    every endpoint, app/tenant/project ID, Topic, Tag, Consumer Group,
@@ -76,7 +88,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    auto-creation or pre-existing resources must not be treated as proof that
    production will provision them. Missing production provisioning evidence
    blocks design completion.
-8. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
+9. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
    duplicate consumption, or repeated external delivery, include
    `Concurrency And Idempotency Ownership`. Use a stable business idempotency
    key and an application-layer atomic claim in a short transaction; persist
@@ -86,10 +98,17 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    optional fallback with proven natural uniqueness, historical cleanup,
    NULL/soft-delete semantics, and a conflict contract. Check-then-insert,
    process-local locks, and random IDs alone are blocked.
-9. For field/status/enum/sync changes, include `Field And Status Reverse
+   When the selected design is version-based optimistic locking, record the
+   exact database atomic compare-and-set statement and affected-row decision:
+   the update predicate contains both the stable row identity and expected
+   version; a zero-row result distinguishes missing data from version conflict.
+   The TDD plan references the `tests.md` concurrent stale-version case proving
+   one winner, one conflict, and one increment. Do not defer this decision to
+   the managed Executor prompt.
+10. For field/status/enum/sync changes, include `Field And Status Reverse
    Impact` and prove writers, readers, filters, derived sync paths, consumers,
    and tests. Direct setter-only design is blocked.
-10. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+11. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
    balance, electricity fee, service fee, package settlement, proration,
    allocation, reconciliation, or financial display changes,
    include `Money Precision Boundary`. Prove calculation-state fields,
@@ -108,12 +127,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    level and policy source, deterministic residual strategy with stable
    tie-breaker, and positive/zero/negative evidence. For FX changes, freeze the
    directional rate metadata and one canonical conversion path.
-11. Record state:
+12. Record state:
    ```bash
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> technical_design docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> design_doc design.md
    ```
-12. Update `design.md` with `Superpowers Technical Design Handoff`, update
+13. Update `design.md` with `Superpowers Technical Design Handoff`, update
    `sdd-quality-gate.md` with the technical design path and hash, then run
    `../superflow-pipeline/scripts/superflow-handoff.sh <change-dir> --refresh`.
    If the guard reports a stale or missing hash, record the printed hash in
@@ -121,7 +140,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    `--refresh` again. Do not set `design_doc` to the Superpowers document;
    `design_doc` is the OpenSpec/SDD contract design, while `technical_design`
    is the Superpowers HOW document.
-13. Run:
+14. Run:
    ```bash
    ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
    ../superflow-pipeline/scripts/superflow-guard.sh <change-dir> design --apply