@chenmk/superflow 0.2.5 → 0.4.0

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

@@ -24,6 +24,7 @@ VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
 CHANGE_DIR="${1:-}"
 PHASE="${2:-}"
 MODE="${3:-}"
+CHANGE_DIR_INPUT="${CHANGE_DIR%/}"
 
 [[ -n "$CHANGE_DIR" && -n "$PHASE" ]] || {
   usage
@@ -35,6 +36,25 @@ MODE="${3:-}"
 CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
 issues=()
 
+require_canonical_change_layout() {
+  local suffix
+
+  if [[ -L "$CHANGE_DIR_INPUT" ]]; then
+    issues+=("symlinked OpenSpec change directory is forbidden; keep one physical openspec/changes/<change-name> directory")
+  fi
+
+  [[ "$CHANGE_DIR" == */openspec/changes/* ]] || return 0
+  suffix="${CHANGE_DIR#*/openspec/changes/}"
+  case "$suffix" in
+    archive/*|*/embedded-changes/*) return 0 ;;
+  esac
+  if [[ "$suffix" == */* ]]; then
+    issues+=("non-canonical OpenSpec change directory: encode the version in <change-name> and use openspec/changes/<change-name>")
+  fi
+}
+
+require_canonical_change_layout
+
 require_file() {
   local path="$1"
   [[ -f "$CHANGE_DIR/$path" ]] || issues+=("missing file: $path")
@@ -178,6 +198,60 @@ require_state_file() {
   require_file .sdd/state.yaml
 }
 
+require_tasks_complete() {
+  local task_count unchecked_count
+  require_file tasks.md
+  [[ -f "$CHANGE_DIR/tasks.md" ]] || return 0
+  task_count="$(grep -Ec '^[[:space:]]*-[[:space:]]+\[[ xX]\]' "$CHANGE_DIR/tasks.md" || true)"
+  unchecked_count="$(grep -Ec '^[[:space:]]*-[[:space:]]+\[[[:space:]]\]' "$CHANGE_DIR/tasks.md" || true)"
+  [[ "$task_count" -gt 0 ]] || issues+=("tasks.md has no checkbox tasks")
+  [[ "$unchecked_count" -eq 0 ]] || issues+=("$unchecked_count unchecked task(s) remain in tasks.md")
+}
+
+verification_report_path() {
+  local value
+  value="$(state_get verification_report)"
+  [[ -n "$value" && "$value" != "null" ]] || return 1
+  if [[ -f "$CHANGE_DIR/$value" ]]; then
+    printf '%s\n' "$CHANGE_DIR/$value"
+    return 0
+  fi
+  if [[ -f "$value" ]]; then
+    printf '%s\n' "$value"
+    return 0
+  fi
+  return 1
+}
+
+require_closeout_markers() {
+  local report="${1:-$CHANGE_DIR/test-report.md}"
+  if [[ ! -f "$report" ]]; then
+    issues+=("verification report path does not exist: $report")
+    return 0
+  fi
+  if ! grep -Eiq '(Verification Result|验证结果|验证结论)[[:space:]:：|*-]*(PASS|通过)' "$report"; then
+    issues+=("verification result PASS marker not found in verification report")
+  fi
+  if ! grep -Eiq '(Archive Readiness|归档就绪)[[:space:]:：|*-]*(PASS|READY|通过|就绪)' "$report"; then
+    issues+=("archive readiness PASS marker not found in verification report")
+  fi
+}
+
+require_branch_handled() {
+  local branch_status
+  branch_status="$(state_get branch_status)"
+  [[ "$branch_status" == "handled" ]] || issues+=("branch_status must be handled before verification closeout")
+}
+
+require_full_verification_fingerprint() {
+  local report="$CHANGE_DIR/test-report.md"
+  [[ "$(state_get verify_mode)" == "full" ]] || return 0
+  require_grep '测试环境|test environment|staging|sandbox' "$report" "full verification test environment"
+  require_grep '分支|提交|版本|构建号|镜像|branch|commit|tag|build|image' "$report" "full verification deployment fingerprint"
+  require_grep 'https?://|Base URL|基础地址' "$report" "full verification base URL"
+  require_grep '验证时间|执行时间|timestamp|verified[_ -]?at|20[0-9]{2}-[0-9]{2}-[0-9]{2}' "$report" "full verification timestamp"
+}
+
 require_spec_doc() {
   if [[ -f "$CHANGE_DIR/spec.md" ]]; then
     return
@@ -259,6 +333,43 @@ change_has_external_enum_risk() {
     "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
 }
 
+change_contract_docs_without_complexity_budget() {
+  local path
+  for path in proposal.md api.md design.md tests.md spec.md; do
+    [[ -f "$CHANGE_DIR/$path" ]] || continue
+    sed -E '/新增项统计|复杂度预算|New-item counts|Complexity budget/d' \
+      "$CHANGE_DIR/$path"
+  done
+  if [[ -d "$CHANGE_DIR/specs" ]]; then
+    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f \
+      -exec sed -E '/新增项统计|复杂度预算|New-item counts|Complexity budget/d' {} +
+  fi
+}
+
+change_all_docs_without_complexity_budget() {
+  find "$CHANGE_DIR" -maxdepth 2 -name '*.md' -type f \
+    -exec sed -E '/新增项统计|复杂度预算|New-item counts|Complexity budget/d' {} +
+}
+
+change_has_external_config_risk() {
+  local content
+  content="$(change_contract_docs_without_complexity_budget)"
+  grep -Eiq \
+    '第三方|外部平台|外部工具|外部集成|third[- ]party|external (platform|tool|integration|system)|SDK|MQ|Kafka|RocketMQ|TDMQ|callback|回调|webhook|支付渠道|payment gateway|cloud service|云服务' \
+    <<< "$content"
+}
+
+change_has_concurrency_idempotency_risk() {
+  grep -RIEiq \
+    '并发|批量下发|批量开通|批量续费|重复提交|重复回调|重复消费|重复下发|幂等|竞态|原子占用|concurren|idempoten|race condition|duplicate (request|callback|consumption|delivery)|atomic claim' \
+    "$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_money_precision_risk() {
   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' \
@@ -282,9 +393,11 @@ change_has_fx_precision_risk() {
 }
 
 change_has_architecture_boundary_risk() {
-  grep -RIEiq \
+  local content
+  content="$(change_all_docs_without_complexity_budget)"
+  grep -Eiq \
     '跨仓|跨服务|sibling|SDK|MQ|topic|consumer|scheduler|定时|device|设备|callback|回调|third[- ]party|第三方|mini[- ]program|小程序|gateway|网关|adapter|适配|protocol|协议|interconnect|互联互通|调用链|入口|出口' \
-    "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
+    <<< "$content"
 }
 
 first_prompt_rel() {
@@ -325,6 +438,33 @@ require_external_enum_contract() {
   require_grep '不确定|阻塞|blocker|unknown|待确认' "$path" "$label unresolved/blocker column"
 }
 
+require_external_config_contract() {
+  local path="$1"
+  local label="$2"
+  require_grep 'External Integration Configuration And Deployment Contract|外部集成配置与部署合同|外部配置.*部署合同' "$path" "$label"
+  require_grep '本地.*测试.*生产|local.*test.*production|local.*staging.*production' "$path" "$label environment matrix"
+  require_grep '注入|创建方式|provision|injection|IaC|Secret|控制台|console' "$path" "$label injection/provisioning"
+  require_grep '运行 owner|创建 owner|provisioning owner|runtime owner|owner.*时点|owner.*time' "$path" "$label owner and timing"
+  require_grep '就绪|readiness|消息轨迹|trace|health' "$path" "$label readiness evidence"
+  require_grep '回滚|rollback|禁用|disable' "$path" "$label rollback"
+  require_grep '密钥|凭据|secret|credential' "$path" "$label secret handling"
+  require_grep '不得.*硬编码|禁止.*硬编码|not.*hard.?cod|must not.*hard.?cod|do not hard.?code' "$path" "$label no hard-coded external config"
+  require_grep '测试.*生产|test.*production|staging.*production' "$path" "$label test-production distinction"
+}
+
+require_concurrency_idempotency_contract() {
+  local path="$1"
+  local label="$2"
+  require_grep 'Concurrency And Idempotency Ownership|并发与幂等归属|应用层原子占用' "$path" "$label"
+  require_grep '业务幂等键|business idempotency key|business key' "$path" "$label business idempotency key"
+  require_grep '应用层原子占用|application.layer atomic claim|atomic claim' "$path" "$label application-layer atomic claim"
+  require_grep '短事务|short transaction|事务边界|transaction boundary' "$path" "$label short transaction boundary"
+  require_grep '待处理|pending|成功|success|失败|failed|状态流转|state machine' "$path" "$label state machine"
+  require_grep '重试|retry' "$path" "$label retry contract"
+  require_grep '外部调用|external call|third.party call' "$path" "$label external-call boundary"
+  require_grep '唯一索引.*(不是|不得|不作为).*默认|unique index.*not.*default|do not.*default.*unique index' "$path" "$label unique index is not the default"
+}
+
 require_money_precision_contract() {
   local path="$1"
   local label="$2"
@@ -379,6 +519,29 @@ require_money_precision_evidence() {
   fi
 }
 
+require_minimal_design_review() {
+  local path="$1"
+  local label="$2"
+  require_grep '复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review' "$path" "$label"
+  require_grep '复用|reuse|existing capability|existing module' "$path" "$label reuse evidence"
+  require_grep '最简|最小实现|simplest|minimum design|minimal implementation' "$path" "$label simplest implementation"
+  require_grep '删除|拒绝|不新增|移出范围|removed|rejected|do not add|out of scope' "$path" "$label removed or rejected complexity"
+  require_grep '新增项统计|复杂度预算|New-item counts|Complexity budget' "$path" "$label complexity budget"
+  require_grep '表|table' "$path" "$label table count"
+  require_grep '字段|field' "$path" "$label field count"
+  require_grep 'API' "$path" "$label API count"
+  require_grep 'Service|服务|组件|service|component' "$path" "$label service/component count"
+  require_grep '缓存|cache' "$path" "$label cache count"
+  require_grep 'MQ|事件|异步|event|async' "$path" "$label async/event count"
+  require_grep '定时任务|scheduled job|scheduler' "$path" "$label scheduled-job count"
+  require_grep '兼容层|compatibility layer' "$path" "$label compatibility-layer count"
+}
+
+require_minimal_design_pass() {
+  local path="$1"
+  require_grep '(复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review).*(PASS|通过)|(PASS|通过).*(复杂度减法评审|反过度设计评审|Minimal Design Review|Complexity Reduction Review)' "$path" "complexity reduction review PASS verdict"
+}
+
 transition_event=""
 
 if [[ -x "$VALIDATE" && -f "$CHANGE_DIR/.sdd/state.yaml" ]]; then
@@ -408,10 +571,23 @@ 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"
+    workflow="$(state_get workflow)"
+    if [[ "$workflow" == "full" ]]; then
+      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
+    fi
     if change_has_external_enum_risk; then
       require_external_enum_contract api.md "external enum binding contract"
       require_external_enum_contract sdd-quality-gate.md "external enum binding quality gate"
     fi
+    if change_has_external_config_risk; then
+      require_external_config_contract api.md "external integration configuration contract"
+      require_external_config_contract sdd-quality-gate.md "external integration deployment gate"
+    fi
+    if change_has_concurrency_idempotency_risk; then
+      require_concurrency_idempotency_contract sdd-quality-gate.md "concurrency and idempotency ownership quality gate"
+    fi
     if change_has_money_precision_risk; then
       require_grep 'Money Precision Boundary|金额精度边界' sdd-quality-gate.md "money precision quality gate"
     fi
@@ -436,6 +612,9 @@ case "$PHASE" in
     require_hash_recorded
     workflow="$(state_get workflow)"
     if [[ "$workflow" == "full" ]]; then
+      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
       require_optional_state_path technical_design "technical_design"
       technical_design_rel="$(state_get technical_design)"
       if [[ -n "${technical_design_rel:-}" && "$technical_design_rel" != "null" ]]; then
@@ -450,9 +629,16 @@ case "$PHASE" in
         if change_has_external_enum_risk; then
           require_external_enum_contract "$technical_design_rel" "external enum binding matrix"
         fi
+        if change_has_external_config_risk; then
+          require_external_config_contract "$technical_design_rel" "external integration configuration and deployment contract"
+        fi
+        if change_has_concurrency_idempotency_risk; then
+          require_concurrency_idempotency_contract "$technical_design_rel" "concurrency and idempotency ownership contract"
+        fi
         if change_has_money_precision_risk; then
           require_money_precision_contract "$technical_design_rel" "money precision boundary"
         fi
+        require_minimal_design_review "$technical_design_rel" "technical design minimal design review"
       fi
     fi
     require_grep 'Superpowers Technical Design Handoff|Superpower 技术详设|technical_design|源码级 HOW' design.md "Superpowers technical design handoff"
@@ -481,6 +667,12 @@ case "$PHASE" in
         if change_has_external_enum_risk; then
           require_external_enum_contract "$prompt_rel" "prompt external enum binding inheritance"
         fi
+        if change_has_external_config_risk; then
+          require_external_config_contract "$prompt_rel" "prompt external integration configuration inheritance"
+        fi
+        if change_has_concurrency_idempotency_risk; then
+          require_concurrency_idempotency_contract "$prompt_rel" "prompt concurrency and idempotency ownership inheritance"
+        fi
         if change_has_money_precision_risk; then
           require_money_precision_contract "$prompt_rel" "prompt money precision inheritance"
         fi
@@ -503,6 +695,7 @@ case "$PHASE" in
     ;;
   verify)
     require_state_file
+    require_tasks_complete
     require_file test-report.md
     require_grep 'RED|失败证据' test-report.md "RED evidence"
     require_grep 'GREEN|通过证据' test-report.md "GREEN evidence"
@@ -512,10 +705,21 @@ case "$PHASE" in
     if change_has_external_enum_risk; then
       require_grep 'External Enum Binding|外部枚举绑定|第三方字段语义绑定|外部展示|展示文案|业务语义|财务语义|BEM|真实入口' test-report.md "external enum binding runtime evidence"
     fi
+    if change_has_external_config_risk; then
+      require_grep 'External Integration Configuration And Deployment Contract|外部集成配置与部署合同' test-report.md "external integration configuration runtime evidence"
+      require_grep '生产.*就绪|production.*ready|provision.*verified|资源.*存在|resource.*exists' test-report.md "external production readiness evidence"
+    fi
+    if change_has_concurrency_idempotency_risk; then
+      require_grep 'Concurrency And Idempotency Ownership|并发与幂等归属|应用层原子占用' test-report.md "concurrency and idempotency runtime evidence"
+      require_grep '并发|concurren|重复|duplicate|重试|retry' test-report.md "concurrency duplicate and retry cases"
+    fi
     if change_has_money_precision_risk; then
       require_money_precision_evidence test-report.md "money precision runtime evidence"
     fi
     require_test_report_lint
+    require_closeout_markers "$CHANGE_DIR/test-report.md"
+    require_branch_handled
+    require_full_verification_fingerprint
     require_markdown_links_valid
     if [[ "$(state_get verification_report)" == "" || "$(state_get verification_report)" == "null" ]]; then
       "$STATE" set "$CHANGE_DIR" verification_report test-report.md
@@ -524,11 +728,20 @@ case "$PHASE" in
     ;;
   archive)
     require_state_file
+    require_tasks_complete
     verify_result="$(state_get verify_result)"
     [[ "$verify_result" == "pass" ]] || issues+=("verify_result must be pass before archive")
     archived="$(state_get archived)"
     [[ "$archived" != "true" ]] || issues+=("archived is already true")
     require_state_value verification_report "verification_report"
+    report_path="$(verification_report_path || true)"
+    if [[ -z "$report_path" ]]; then
+      issues+=("verification_report path does not exist")
+    else
+      require_closeout_markers "$report_path"
+    fi
+    require_branch_handled
+    require_state_value verified_at "verified_at"
     transition_event="archived"
     ;;
   *)

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

@@ -111,6 +111,13 @@ Before pass:
    complement.
 7. Branch/worktree status is handled and `.sdd/state.yaml` has:
    `branch_status: handled`.
+8. Every checkbox in `tasks.md` is checked. A completed implementation with
+   stale task documentation is a verification failure, not an archive-time
+   cleanup item.
+9. `test-report.md` ends with the machine-checkable closeout markers
+   `验证结果: PASS` and `归档就绪: PASS`. For `verify_mode: full`, it also
+   records the test environment, branch/commit/build or image fingerprint,
+   Base URL, and verification timestamp.
 
 Only then run:
 

package/assets/skills-en/openspec-propose/SKILL.md

@@ -22,6 +22,20 @@ When ready to implement, run /opsx:apply
 
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
+### Canonical OpenSpec Change Directory (Blocking)
+
+- A change must have exactly one physical directory:
+  `openspec/changes/<name>/`.
+- Encode the release version in `<name>`. For example, an account-permission
+  change for `v1.1.1` must use `v1-1-1-account-permission-optimization`.
+- Do not create nested version directories such as
+  `openspec/changes/v1.1.1/<feature>/`.
+- Do not create a flat symlink, copied directory, or second canonical document
+  tree to work around OpenSpec CLI discovery.
+- Creation, status, validation, and apply must use the same `<name>` in
+  `openspec new change`, `openspec status --change`, and
+  `openspec validate <name> --strict`.
+
 **Steps**
 
 1. **If no clear input provided, ask what they want to build**

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

@@ -14,6 +14,10 @@ do not mark archived until the user confirms final closeout.
 - `phase: archive`.
 - `verify_result: pass`.
 - `verification_report` points to an existing report.
+- Every checkbox in `tasks.md` is checked.
+- The verification report contains `Verification Result: PASS` and
+  `Archive Readiness: PASS`.
+- `branch_status: handled` and `verified_at` are recorded.
 - `superflow-state.sh recover <change-dir>` gives a coherent archive recovery action.
 
 ## Procedure
@@ -42,6 +46,8 @@ do not mark archived until the user confirms final closeout.
   the user explicitly accepts the boundary.
 - Do not use archive to hide missing API, DB, hook, SQL, test-report, or real
   integration evidence.
+- Never call `openspec archive` directly to bypass the lifecycle gate. The
+  installed archive-command hook blocks that path when native hooks are active.
 - In a standard `openspec/changes/<name>` layout, archive must use OpenSpec
   archive semantics so delta specs are merged and the change is moved to
   `openspec/changes/archive/`. State-only archive is only a fallback for

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

@@ -50,6 +50,15 @@ any full SDD document or implementation prompt is generated.
   external input. If semantics are unclear, mark the feature blocked instead of
   inventing a fallback.
 - Process one feature at a time, in product-document order.
+- When the pipeline selected embedded deep-clarification mode, investigate facts
+  from the repository, source documents, configuration, tests, logs, and tools
+  before asking. Ask the user only about an unresolved decision that needs owner
+  intent; do not ask for facts that can be found locally.
+- In embedded deep-clarification mode, ask exactly one decision question at a
+  time. Include the recommended answer and its important consequence, wait for
+  the answer, then record the result before asking the next question. Do not
+  create SDD artifacts or implementation prompts while a current-feature
+  decision remains pending.
 - For long PRDs, Lark/Feishu exports, screenshots, or mixed product docs, do
   not read the whole document and generate all tasks in one pass. First create
   a source index, then process one bounded section or feature at a time. Each
@@ -85,6 +94,10 @@ Create or update these files in the active OpenSpec change directory:
 - Business semantic evidence when status/enum/sync/default behavior is involved:
   source-of-truth field, enum mapping, consumer interpretation, business basis,
   explicitly rejected fallback/default choices, and unresolved owner questions.
+- Deep-clarification decision evidence when this mode is active: each question,
+  recommendation, user decision, consequence, and the resulting
+  `confirmed`/`candidate`/`pending`/`rejected` entry in
+  `.sdd/handoff/brainstorm-summary.md`.
 
 Use the detailed workflow in:
 
@@ -127,14 +140,20 @@ Use the detailed workflow in:
     If a proposed default, fallback, old-value retention, or null conversion is
     not explicitly approved by the requirement or owner, mark it rejected and do
     not include it in the design.
-11. Ask only current-feature clarification questions.
-12. Wait for programmer confirmation.
-13. Draft a rough API contract: path, action, core request, core response. Field types can be approximate.
-14. Wait for programmer confirmation of the rough API.
-15. Produce a precise API section with field names, types, requiredness, defaults, enums, errors, examples, and curl.
-16. Mark the feature as `frozen` only when understanding, rough API, precise API,
+11. If embedded deep-clarification mode is active, resolve one decision at a
+    time. For each question, state the recommended answer and consequence, wait
+    for the programmer response, then update
+    `.sdd/handoff/brainstorm-summary.md` under `confirmed`, `candidate`,
+    `pending`, or `rejected`. Stop asking once only repository-verifiable facts
+    remain.
+12. Ask only any remaining current-feature clarification questions.
+13. Wait for programmer confirmation.
+14. Draft a rough API contract: path, action, core request, core response. Field types can be approximate.
+15. Wait for programmer confirmation of the rough API.
+16. Produce a precise API section with field names, types, requiredness, defaults, enums, errors, examples, and curl.
+17. Mark the feature as `frozen` only when understanding, rough API, precise API,
     and validation data needs are confirmed or explicitly blocked.
-17. Only after the current feature is frozen or blocked, move to the next
+18. Only after the current feature is frozen or blocked, move to the next
     indexed feature. Do not batch-confirm multiple features from memory or a
     compressed chat summary.
 

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

@@ -46,7 +46,17 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 4. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-5. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
+5. 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
+   insufficient. Prefer one owner, one write path, one transaction, and
+   set-based operations when they satisfy the contract. Remove speculative
+   extension points, duplicate DTO/API layers, derivable persistence,
+   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,
    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
@@ -54,10 +64,32 @@ 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.
-6. For field/status/enum/sync changes, include `Field And Status Reverse
+7. 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,
+   namespace, webhook, ACL/role, feature switch, timeout, and credential
+   reference. Prove the source and injection/provisioning method for local,
+   test, and production environments, plus owner, creation timing, readiness
+   check, rollback, and unresolved blockers. Runtime values and server-side
+   resources must not exist only as hard-coded annotations/constants. Test
+   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,
+   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
+   `PENDING` before the external call, release database locks before calling
+   externally, model success/failure/uncertain states, and reuse the original
+   business code on retry. A unique index is not the default and may only be an
+   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
    Impact` and prove writers, readers, filters, derived sync paths, consumers,
    and tests. Direct setter-only design is blocked.
-7. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+10. 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,
@@ -76,12 +108,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.
-8. Record state:
+11. 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
    ```
-9. Update `design.md` with `Superpowers Technical Design Handoff`, update
+12. 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
@@ -89,7 +121,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.
-10. Run:
+13. Run:
    ```bash
    ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
    ../superflow-pipeline/scripts/superflow-guard.sh <change-dir> design --apply

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

@@ -76,6 +76,17 @@ For complex requirements, verify these before writing docs:
   If the docs only prove that a value exists, is non-null, or lets the request
   succeed, stop and return to `$superflow-clarify`. If fallback/default/keep-old-value
   behavior is proposed without explicit requirement or owner approval, stop.
+- For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment gateways,
+  cloud services, or other external integrations, `api.md` and
+  `sdd-quality-gate.md` must include `External Integration Configuration And
+  Deployment Contract`. Inventory endpoints, app/tenant/project IDs,
+  Topic/Tag/Consumer Group, namespace, webhook, ACL/role, feature switches,
+  timeout, and credential references across local, test, and production
+  environments. Record injection/provisioning method, runtime owner,
+  provisioning owner/time, readiness evidence, rollback, secret handling, and
+  blockers. Environment-dependent values must not be hard-coded; test
+  auto-creation or existing test resources do not prove production readiness.
+  Missing production provisioning evidence blocks document freeze.
 - For amount, fee, discount, deduction, refund, sharing, payment, invoice,
   balance, electricity/service fee, package settlement, proration, allocation,
   reconciliation, or financial display changes, `sdd-quality-gate.md` must
@@ -92,6 +103,17 @@ For complex requirements, verify these before writing docs:
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
   any gate is missing from `design.md`, `tests.md`, or quality gate, stop and
   complete the docs first.
+- For full workflow changes, `design.md` must include a `Minimal Design Review`
+  before docs freeze. Inventory every proposed table, field, API,
+  service/component, cache, async/MQ/event flow, scheduled job, compatibility
+  layer, and abstraction. Record existing reuse evidence, necessity, the
+  simplest implementation, removed/rejected complexity, and blockers.
+  Prefer extending current modules and synchronous transactions. Do not keep a
+  layer only for hypothetical future flexibility; remove it without evidence.
+- `sdd-quality-gate.md` must record the minimal-design verdict as `PASS` or
+  `BLOCKED`; only `PASS` may leave docs/design. Missing reuse evidence, parallel APIs/models, redundant persisted
+  fields, speculative cache/async/compensation, or an unresolved simpler option
+  blocks docs completion.
 - `design.md` stays the OpenSpec/SDD design contract: requirement mapping,
   API/DB/field semantics, source facts, real-entry call chain, no-fallback
   boundary, risks, and acceptance hooks. It must not try to own all source-level
@@ -240,6 +262,11 @@ Use references only as needed:
   the relationship judgment as `confirmed/partially confirmed/unknown` when a bug fix hinges on
   existing data or call-chain behavior.
 - `design.md` must reference the frozen `api.md` fields and errors.
+- `design.md` must include `Minimal Design Review` with:
+  `Design item | Existing capability/reuse evidence | Necessary? | Simplest implementation | Removed/rejected complexity | Evidence/blocker`.
+  Count new tables, fields, APIs, services/components, caches, async flows,
+  jobs, and compatibility layers. A zero count is valid and preferred when
+  existing capabilities close the contract.
 - `design.md` must include a "Field Semantic Contract" table for every risky field:
   `Field | Source table/DTO/event | Real semantics | Target field | Target semantics | Equivalent? |
   Evidence anchor | Forbidden usage | Unknowns/owner`.