@chenmk/superflow 0.2.5 → 0.3.0

package/README.md

@@ -206,7 +206,10 @@ hook registration is not enabled for OpenCode yet; use `/superflow-*` commands
 to run workflow gates explicitly.
 
 For large requirements, ask the agent to read one section or one feature at a
-time. SuperBridge Flow will route through clarification, OpenSpec docs,
+time. The total router automatically uses embedded deep clarification when a
+feature needs an owner decision; it investigates available facts first and asks
+one decision at a time with a recommendation. Clear, bounded work continues
+without an interview. SuperBridge Flow then routes through OpenSpec docs,
 Superpowers technical design, implementation prompts, verification, and archive.
 
 ## Automatic Update Checks

package/README.zh-CN.md

@@ -121,6 +121,7 @@ superflow init
 - Superpowers 负责 HOW：源码级技术详设、TDD/RED 顺序、团队分工、worktree/端口并行、review/tester 编排和验证闭环。
 - 完整流程是 `docs -> design -> implement -> verify -> archive`。Superpowers 技术详设落到 `docs/superpowers/specs/*-technical-design.md`，并记录到 `.sdd/state.yaml` 的 `technical_design`，避免长会话压缩后漂移。
 - Codex 侧通常用自然语言或 `$superflow-pipeline` 触发；Claude Code 侧可以直接用 `/superflow-pipeline`、`/superflow-docs`、`/superflow-design` 等 slash command。
+- 只说一句话触发总路由时，遇到需要业务负责人选择的关键分歧，SuperFlow 会在 clarify 阶段自动进入深度澄清：先查代码和已有资料能确认的事实，再一次只问一个决策问题，并给出推荐方案与影响。明确、范围小的改动不会被强行拉进问答流程。
 - 飞书、语雀等在线文档读取工具不内置在 SuperBridge Flow CLI 中；可自行用 `lark-cli` 等外部工具读取，再通过 `/superflow-pipeline` 或 `$superflow-pipeline` 分段分析指定小节。
 
 ## 命令

package/assets/manifest.json

@@ -29,6 +29,7 @@
     "superflow-hook-guard.sh",
     "superflow-dependency-update-hook.sh",
     "superflow-integration-evidence-hook.sh",
+    "superflow-archive-command-hook.sh",
     "superflow-test-report-lint.py",
     "install-sql-pre-commit.sh",
     "sync-settings-json.py"
@@ -45,7 +46,8 @@
     "superflow-dependency-update-hook.sh",
     "superflow-sql-sync-hook.py",
     "superflow-delivery-check.sh",
-    "superflow-integration-evidence-hook.sh"
+    "superflow-integration-evidence-hook.sh",
+    "superflow-archive-command-hook.sh"
   ],
   "agentHooks": {
     "claude": ["claude-auto-backup-hook.sh"],

package/assets/prompts/superflow-clarify.md

@@ -8,3 +8,9 @@ Use the `superflow-clarify` skill for this request.
 Read the requested source in bounded sections, freeze one feature or section at
 a time, and stop for missing product/API/DB facts before OpenSpec artifacts are
 created.
+
+If the total router selected embedded deep clarification, establish facts from
+the repository and supplied sources before asking. Ask one unresolved owner
+decision at a time, include a recommended answer and consequence, wait for the
+response, and record the result in the existing brainstorm handoff before moving
+on. Do not turn clear, bounded work into an interview.

package/assets/prompts/superflow-pipeline.md

@@ -9,5 +9,13 @@ Route the work through the correct SuperBridge Flow phase. OpenSpec owns WHAT
 and contracts; Superpowers owns source-level HOW. Preserve handoff state and run
 the required SuperBridge Flow guards before phase transitions.
 
+When the request has unresolved decisions that need owner intent, competing
+approaches, unclear source of truth, unclear acceptance behavior, or cross-system
+responsibility, enter the embedded deep-clarification mode of
+`superflow-clarify`. Investigate repository-verifiable facts first, then ask one
+decision question at a time with a recommended answer and consequence. Keep the
+decision record in the existing brainstorm handoff. Do not require the user to
+invoke another command, and do not use this mode for a clear bounded change.
+
 Input: treat the argument after `/superflow-pipeline` as the requirement,
 document path, or change description.

package/assets/scripts/superflow-archive-command-hook.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Blocks direct OpenSpec/Superflow archive commands that bypass lifecycle gates.
+
+set -u
+
+INPUT=$(cat)
+
+read_json_field() {
+  local field="$1"
+  printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print('')
+    raise SystemExit
+tool_input = data.get('tool_input', {})
+print(tool_input.get('$field') or tool_input.get('cmd') or '')
+" 2>/dev/null
+}
+
+COMMAND=$(read_json_field command)
+[ -n "$COMMAND" ] || exit 0
+
+CHANGE=$(printf '%s' "$COMMAND" | python3 -c '
+import shlex, sys
+
+try:
+    tokens = shlex.split(sys.stdin.read())
+except ValueError:
+    raise SystemExit
+
+for index in range(len(tokens) - 1):
+    binary = tokens[index].rsplit("/", 1)[-1]
+    if binary not in {"openspec", "superflow"} or tokens[index + 1] != "archive":
+        continue
+    skip_value = False
+    for token in tokens[index + 2:]:
+        if skip_value:
+            skip_value = False
+            continue
+        if token in {"--store", "--agent"}:
+            skip_value = True
+            continue
+        if token.startswith("-"):
+            continue
+        print(token)
+        raise SystemExit
+' 2>/dev/null)
+
+[ -n "$CHANGE" ] || exit 0
+
+CWD=$(read_json_field cwd)
+[ -n "$CWD" ] || CWD=$(pwd)
+REPO_ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null) || exit 0
+
+if [ -d "$CWD/$CHANGE" ]; then
+  CHANGE_DIR="$CWD/$CHANGE"
+else
+  CHANGE_DIR="$REPO_ROOT/openspec/changes/$CHANGE"
+fi
+
+[ -d "$CHANGE_DIR" ] || exit 0
+
+ARCHIVE_SCRIPT=${SUPERFLOW_ARCHIVE_SCRIPT:-$HOME/.codex/skills/superflow-pipeline/scripts/superflow-archive.sh}
+if [ ! -x "$ARCHIVE_SCRIPT" ]; then
+  echo "[Superflow 归档门禁] 归档脚本不存在或不可执行：$ARCHIVE_SCRIPT" >&2
+  exit 2
+fi
+
+if ! "$ARCHIVE_SCRIPT" "$CHANGE_DIR" --dry-run; then
+  cat <<'BLOCK_MSG' >&2
+[Superflow 归档门禁] 归档门禁未通过，已阻止直接归档。
+请先完成 tasks、test-report、测试环境证据、verify 状态和归档确认；
+不要用 openspec archive 绕过 Superflow 生命周期。
+BLOCK_MSG
+  exit 2
+fi
+
+exit 0

package/assets/scripts/superflow-delivery-check.sh

@@ -52,27 +52,46 @@ if [ -z "$CHANGED" ]; then
   exit 0
 fi
 
+ACTIVE_SDD_CHANGED=$(printf '%s\n' "$CHANGED" | grep -Ev \
+  '(^|/)(doc/)?openspec/changes/archive/' || true)
+
 SDD_ACTIVE=0
 if [ -f "$REPO_ROOT/.sdd-enforced" ]; then
   SDD_ACTIVE=1
 fi
 
+if [ "$SDD_ACTIVE" -eq 0 ]; then
+  ACTIVE_STATE=$(find "$REPO_ROOT/openspec/changes" \
+    -path '*/archive/*' -prune -o \
+    -path '*/.sdd/state.yaml' -type f -print 2>/dev/null \
+    | while IFS= read -r state; do
+        phase=$(awk -F':' '$1=="phase"{gsub(/^[ \t]+|[ \t]+$/, "", $2); print $2}' "$state")
+        archived=$(awk -F':' '$1=="archived"{gsub(/^[ \t]+|[ \t]+$/, "", $2); print $2}' "$state")
+        if [ "$archived" != "true" ] && { [ "$phase" = "implement" ] || [ "$phase" = "verify" ]; }; then
+          printf '%s\n' "$state"
+        fi
+      done | head -n 1)
+  if [ -n "$ACTIVE_STATE" ]; then
+    SDD_ACTIVE=1
+  fi
+fi
+
 RUNTIME_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
   '(^|/)src/main/.*\.(java|xml|yml|yaml|properties)$|(^|/)mapper/.*\.xml$|(^|/)sql/.*\.sql$' || true)
 
 CODE_RUNTIME_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
   '(^|/)src/main/.*\.(java|xml|yml|yaml|properties)$|(^|/)mapper/.*\.xml$' || true)
 
-P_DIRS=$(printf '%s\n' "$CHANGED" | sed -nE \
+P_DIRS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | sed -nE \
   's#^(.*embedded-changes/(p[0-9]+[^/]*))/.*$#\1#p' | sort -u)
 
-REPORTS=$(printf '%s\n' "$CHANGED" | grep -E \
+REPORTS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | grep -E \
   '(^|/)embedded-changes/p[0-9][^/]*/test-report\.md$|(^|/)test-report\.md$' || true)
 
-AGGREGATE_DOCS=$(printf '%s\n' "$CHANGED" | grep -E \
+AGGREGATE_DOCS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | grep -E \
   '(^|/)openspec/changes/[^/]+/(tasks|test-report|traceability-matrix|sdd-quality-gate|tests)\.md$|(^|/)doc/openspec/changes/[^/]+/(tasks|test-report|traceability-matrix|sdd-quality-gate|tests)\.md$' || true)
 
-SDD_DOCS_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
+SDD_DOCS_CHANGED=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | grep -E \
   '(^|/)(doc/)?openspec/changes/|(^|/)embedded-changes/p[0-9]' || true)
 
 AGGREGATE_ALLOWED=0

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

@@ -14,6 +14,9 @@ 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 `验证结果: PASS` and `归档就绪: PASS`.
+- `branch_status: handled` and `verified_at` are recorded.
 - `superflow-state.sh recover <change-dir>` gives a coherent archive recovery action.
 
 ## Procedure
@@ -42,6 +45,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/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 `已冻结` 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 `已冻结` 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/superflow-design/SKILL.md

@@ -54,17 +54,39 @@ 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
+6. 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.
+7. 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.
+8. 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 third-party, SDK, BEM/parking, payment/refund, financial display,
+9. For third-party, SDK, BEM/parking, payment/refund, financial display,
    source/origin, status sync, or external dictionary fields, include
    `External Enum Binding`. Prove local source fields/enums, external fields,
    external enum values, display/business/financial meaning, source evidence,
    owner confirmation, unresolved handling, and test evidence. A request
    succeeding or a field being non-null is not enough; unconfirmed values are
    blockers and must be returned to `$superflow-docs` or the user.
-8. 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,
@@ -83,12 +105,12 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    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.
-9. 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
    ```
-10. 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
@@ -96,7 +118,7 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    `--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.
-11. Run:
+13. Run:
 
 ```bash
 ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>

package/assets/skills/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 third-party, SDK, BEM/parking, payment/refund, financial display,
   source/origin, status sync, or external dictionary/enum fields, `api.md` and
   `sdd-quality-gate.md` must include `外部枚举绑定确认` / `External Enum

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

@@ -11,6 +11,12 @@ This is the lightweight SDD router. Do not load the whole SDD process when a sma
 
 - Use `$openspec-explore` when the user is still thinking through a requirement,
   wants to compare options, or needs codebase investigation before a change.
+- Route to `$superflow-clarify` in embedded deep-clarification mode when the
+  user explicitly asks for rigorous questioning, or when a bounded feature has
+  unresolved owner decisions, mutually exclusive approaches, unclear source of
+  truth, unclear acceptance behavior, or cross-system responsibility. This is
+  a mode inside the normal clarify phase, not a separate command the user must
+  remember.
 - Use `$superflow-clarify` only when product inputs are complex and must be frozen one
   feature at a time before creating OpenSpec artifacts.
 - Long PRDs, Lark/Feishu exports, screenshot-heavy requirements, and mixed
@@ -49,6 +55,29 @@ This is the lightweight SDD router. Do not load the whole SDD process when a sma
   SQL change, status field, Mapper/XML query, or cross-repo shared table affects
   database-backed behavior.
 
+## Embedded Deep Clarification
+
+When the router selects embedded deep clarification, follow these rules inside
+`$superflow-clarify`:
+
+- Do not activate it for a clear, bounded hotfix or tweak whose intended behavior
+  and acceptance result are already evidenced. Do not turn routine work into an
+  interview.
+- Explore facts that can be established from the requirement, repository,
+  configuration, tests, logs, or available tools before asking the user. Ask only
+  for a decision the user or owner must make.
+- Ask exactly one decision question at a time. State the recommended option and
+  its important consequence, then wait for the answer before the next question.
+- After each answer, update `.sdd/handoff/brainstorm-summary.md` with
+  `confirmed`, `candidate`, `pending`, and `rejected` entries. Do not rely on
+  chat memory for a resolved decision.
+- Do not create or change proposal, spec, design, tasks, tests, or implementation
+  artifacts until all decisions that affect the current feature are confirmed or
+  explicitly marked blocked.
+- Exit deep clarification once only repository-verifiable facts remain and the
+  user confirms the current feature understanding. Continue through the existing
+  clarify workflow without invoking an external skill dependency.
+
 ## Non-Negotiable Rules
 
 ### 上下文防漂移与状态门禁（阻塞级）

package/assets/skills/superflow-pipeline/references/api-design-template.md

@@ -439,6 +439,14 @@ D. 复用某个已有接口的数据权限规则，请指定参考接口
 | --- | -------- | -------- | -------- | ---------------------------------- | ------------- | ----------------------- | -------------------------------- | -------------------------- |
 | 1   | XX SDK   | Java SDK | 1.2.3    | 页面表单提交 -> DTO -> SDK Request | appId: 应用ID | {"code":0,"data":{...}} | {"code":500,"message":"timeout"} | 记录阻塞证据，标记外部阻塞 |
 
+### 外部集成配置与部署合同
+
+涉及第三方平台/工具、SDK、MQ/Kafka、回调、支付渠道或云服务时必须填写。
+
+| 外部依赖/资源 | 配置项/资源名 | 本地来源/创建方式 | 测试来源/创建方式 | 生产来源/创建方式 | 注入/创建方式 | 运行 owner | 创建 owner/时点 | 就绪证据 | 回滚方式 | 密钥处理 | 阻塞项 |
+| ------------- | ------------- | ----------------- | ----------------- | ----------------- | ------------- | ---------- | --------------- | -------- | -------- | -------- | ------ |
+| TDMQ          | Consumer Group | 自动/手工/IaC    | 已存在/自动创建   | 运维发版前预创建  | 配置/Secret/IaC/控制台 | ydt-energy | 运维/发版前 | 控制台/API/消息轨迹 | 禁用消费/版本回滚 | 仅记录 Secret 引用 | 无/Blocked |
+
 ### 外部枚举绑定确认
 
 涉及第三方、SDK、BEM/停车系统、支付/退款、财务展示、来源字段、状态同步、
@@ -452,6 +460,9 @@ D. 复用某个已有接口的数据权限规则，请指定参考接口
 ### 外部依赖红线
 
 - SDK 参数来源必须写明，不得凭字段名猜测含义。
+- 环境相关 endpoint、资源名、标识、凭据、ACL 和运行开关不得只硬编码在注解、常量或业务代码中。
+- 测试环境自动创建、历史资源已存在或应用本地启动成功，不得作为生产资源已就绪的证据。
+- Topic、Consumer Group、namespace、webhook、应用/租户 ID 等服务端资源必须明确生产创建 owner、创建时点、就绪检查和回滚方式；缺失时阻塞发布。
 - SDK 版本变更必须记录原因和影响范围。
 - 真实环境可用时，不得仅用 mock 代替。必须在 tests.md 记录真实请求/响应。
 - 外部服务不可用时，只能标记为"外部阻塞"或"Mock 验证"，不得宣称真实链路通过。

package/assets/skills/superflow-pipeline/references/batch-prompt-template.md

@@ -181,6 +181,33 @@ Superpowers 技术详设复制 `外部枚举绑定确认` / `External Enum Bindi
 禁止用请求成功、值非空或字段存在替代外部枚举业务语义确认。未确认的外部枚举、
 支付来源、财务展示含义或兜底映射，必须停止并报告 `Blocked`。
 
+## 外部集成配置与部署合同（强制）
+
+如果本批涉及第三方平台/工具、SDK、MQ/Kafka、回调、支付渠道或云服务，必须从
+api.md / sdd-quality-gate.md / Superpowers 技术详设复制
+`外部集成配置与部署合同` / `External Integration Configuration And Deployment Contract`。
+
+| 外部依赖/资源 | 配置项/资源名 | 本地来源/创建方式 | 测试来源/创建方式 | 生产来源/创建方式 | 注入/创建方式 | 运行 owner | 创建 owner/时点 | 就绪证据 | 回滚 | 密钥处理 | 阻塞项 |
+| ------------- | ------------- | ----------------- | ----------------- | ----------------- | ------------- | ---------- | --------------- | -------- | ---- | -------- | ------ |
+| \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | 配置/Secret/IaC/控制台 | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | 仅引用 | 无/Blocked |
+
+环境相关配置和服务端资源不得只硬编码在注解、常量或业务代码中。测试自动创建或
+历史资源存在不能证明生产就绪；缺少生产创建与验证证据时必须停止并报告 `Blocked`。
+
+## 并发与幂等归属（强制）
+
+如果本批涉及并发、批量下发/开通/续费、重复提交/回调/消费或重复外部调用，必须从
+sdd-quality-gate.md / Superpowers 技术详设复制 `Concurrency And Idempotency Ownership`。
+
+| 场景 | 业务幂等键 | 原子占用 owner | 应用层原子占用 | 短事务边界 | 状态流转 | 重试复用编码 | 外部调用边界 | 不确定结果处理 | 唯一索引角色 | 测试证据 |
+| ---- | ---------- | -------------- | ---------------- | ---------- | -------- | ------------ | ------------ | -------------- | ------------ | -------- |
+| ____ | ____ | ____ | 锁定 owner 后写 PENDING | 独立提交 | PENDING/SUCCESS/FAILED | 复用原业务单号 | 提交后调用 | 阻止重复并对账 | 非默认/可选兜底 | 并发/重复/重试 |
+
+默认采用应用层原子占用：稳定业务幂等键、短事务占用并落 `PENDING`、提交并释放锁后
+再调用外部系统。禁止“先查再插”、单进程锁、随机单号和外部调用期间持有长事务。
+唯一索引不是默认方案，只有自然唯一、历史清理、NULL/软删除和冲突合同明确后才可
+作为数据库兜底。结果不确定时必须阻止重复调用并进入可追踪对账。
+
 ## 金额精度边界继承（强制）
 
 如果本批涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、

package/assets/skills/superflow-pipeline/references/implementation-prompt-template.md

@@ -148,7 +148,35 @@ Superpowers 技术详设复制 `外部枚举绑定确认` / `External Enum Bindi
 禁止用请求成功、值非空或字段存在替代外部枚举业务语义确认。未确认的外部枚举、
 支付来源、财务展示含义或兜底映射，必须停止并报告 `Blocked`。
 
-### 1.2 金额精度边界继承
+### 1.2 外部集成配置与部署合同
+
+如果本批涉及第三方平台/工具、SDK、MQ/Kafka、回调、支付渠道或云服务，必须从
+api.md / sdd-quality-gate.md / Superpowers 技术详设复制 `外部集成配置与部署合同`：
+
+| 外部依赖/资源 | 配置项/资源名 | 本地来源/创建方式 | 测试来源/创建方式 | 生产来源/创建方式 | 注入/创建方式 | 运行 owner | 创建 owner/时点 | 就绪证据 | 回滚 | 密钥处理 | 阻塞项 |
+| ------------- | ------------- | ----------------- | ----------------- | ----------------- | ------------- | ---------- | --------------- | -------- | ---- | -------- | ------ |
+| \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | 配置/Secret/IaC/控制台 | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | \_\_\_\_ | 仅引用 | 无/Blocked |
+
+环境相关配置和服务端资源不得只硬编码在注解、常量或业务代码中。测试自动创建、
+测试历史资源存在或应用本地启动成功，不能证明生产已就绪；缺少生产创建 owner、
+创建时点、就绪证据或回滚方式时，必须停止并报告 `Blocked`。
+
+### 1.2.1 并发与幂等归属
+
+如果本批涉及并发、批量下发/开通/续费、重复提交/回调/消费或重复外部调用，必须
+从 sdd-quality-gate.md / Superpowers 技术详设复制 `Concurrency And Idempotency
+Ownership` / `并发与幂等归属`：
+
+| 场景 | 业务幂等键 | 原子占用 owner | 应用层原子占用 | 短事务边界 | 状态流转 | 重试复用编码 | 外部调用边界 | 不确定结果处理 | 唯一索引角色 | 测试证据 |
+| ---- | ---------- | -------------- | ---------------- | ---------- | -------- | ------------ | ------------ | -------------- | ------------ | -------- |
+| ____ | ____ | ____ | 锁定 owner 后写 PENDING | 独立提交 | PENDING/SUCCESS/FAILED | 复用原业务单号 | 提交后调用 | 阻止重复并对账 | 非默认/可选兜底 | 并发/重复/重试 |
+
+默认使用应用层原子占用和稳定业务幂等键，在短事务内持久化 `PENDING` 后提交，释放
+数据库锁再调用外部系统；重试复用原业务编码，结果不确定时阻止重复并进入对账。
+禁止“先查再插”、单进程锁、随机单号或跨外部调用的长事务。唯一索引不是默认方案，
+只有自然唯一、历史数据清理、NULL/软删除和冲突处理合同明确后才可作为可选兜底。
+
+### 1.3 金额精度边界继承
 
 如果本批涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、
 服务费、套餐结算、比例分摊、明细分配、对账或财务展示，必须从 Superpowers

package/assets/skills/superflow-pipeline/references/quality-gate.md

@@ -63,6 +63,8 @@
 | 45   | **SDD 状态机字段**                 | **所有进入实现的任务强制**                                                              | `.sdd/state.yaml` 包含 workflow、phase、handoff_hash、build_mode、isolation、tdd_mode、review_mode、verify_mode、implementation_prompt、verification_report、archived；`superflow-state.sh status/next/recover` 输出一致                                                                                                   |
 | 46   | **外部枚举绑定确认**               | **涉及第三方、SDK、BEM/停车、支付退款、财务展示、来源字段、状态同步或外部字典时强制**   | api.md、sdd-quality-gate.md 和 Superpowers 技术详设包含 `外部枚举绑定确认` / `External Enum Binding`，列出 `业务字段                                                                                                                                                                                                       | 本系统真源字段/枚举 | 外部系统字段       | 外部枚举/字典值      | 展示文案/业务语义/财务语义 | 取值来源     | owner/确认时间                                                                                                | 不确定项/阻塞处理                                                                                                        | 测试证据`；不得用请求成功、值非空或字段存在替代业务语义确认；未确认时必须阻塞 |
 | 47   | **金额精度边界**                   | **涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、服务费、套餐结算、比例分摊、明细分配、对账或财务展示时强制** | Superpowers 技术详设包含 `Money Precision Boundary` 及金额恒等式、权威总额、独立计算项、差额反推项与公式、计算态来源、中间精度、舍入边界、scale/rounding mode、分配/对账规则、禁止提前舍入点和测试证据；存在加法恒等式且总额是真源时，最后一个组成项必须由权威总额减去其余组成项合计得到，禁止所有组成项分别计算和舍入后重建总额；测试必须覆盖半分、尾差或多明细分配场景 |
+| 48   | **外部集成配置与部署合同**         | **涉及第三方平台/工具、SDK、MQ/Kafka、回调、支付渠道、云服务或其他外部集成时强制** | api.md、sdd-quality-gate.md、Superpowers 技术详设和实现 prompt 包含 `外部集成配置与部署合同` / `External Integration Configuration And Deployment Contract`；列出 endpoint、应用/租户/项目 ID、Topic/Tag/Consumer Group、namespace、webhook、ACL/role、开关、超时和凭据引用在本地/测试/生产的来源与创建方式，以及注入方式、运行 owner、创建 owner/时点、就绪证据、回滚、密钥处理和阻塞项；环境相关值不得只硬编码在注解/常量/业务代码；测试自动创建、历史资源或本地启动成功不能证明生产就绪，缺少生产创建证据必须阻塞发布 |
+| 49   | **并发与幂等归属**                 | **涉及并发、批量下发/开通/续费、重复提交/回调/消费或重复外部调用时强制** | sdd-quality-gate.md、Superpowers 技术详设和实现 prompt 包含 `Concurrency And Idempotency Ownership` / `并发与幂等归属`；明确业务幂等键、应用层原子占用 owner、短事务边界、PENDING/SUCCESS/FAILED 状态流转、重试复用原业务编码、外部调用边界和不确定结果对账；唯一索引不作为默认方案，只能在自然唯一、历史数据、NULL/软删除和冲突处理合同明确后作为可选兜底；测试覆盖并发、重复和重试 |
 
 ### 文档完整性强制检查（新增，全部项目必做）
 

package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md

@@ -60,6 +60,47 @@ orchestrator unless the OpenSpec/SDD contract explicitly says that module owns
 the new entry point and records the owner approval. If the correct owner is
 unclear, mark the design blocked.
 
+## External Integration Configuration And Deployment Contract
+
+Use this whenever the change integrates with a third-party platform/tool, SDK,
+MQ/Kafka, callback, payment gateway, cloud service, or other external system.
+
+| External dependency/resource | Config/resource item | Local source/provisioning | Test source/provisioning | Production source/provisioning | Injection/creation method | Runtime owner | Provisioning owner/time | Readiness evidence | Rollback | Secret handling | Blocker |
+| ---------------------------- | -------------------- | ------------------------- | ------------------------ | ------------------------------ | ------------------------- | ------------- | ----------------------- | ------------------ | -------- | --------------- | ------- |
+| `<TDMQ>` | `<Consumer Group>` | `<auto/manual/IaC>` | `<existing resource>` | `<pre-created by ops>` | `<config/secret/IaC/console>` | `<service>` | `<owner + before deploy>` | `<console/API/trace>` | `<disable/rollback>` | `<secret reference only>` | `<none/blocker>` |
+
+Required checks:
+
+```bash
+rg -ni "https?://|endpoint|base.?url|app.?id|tenant|project.?id|topic|tag|consumer.?group|namespace|webhook|acl|role|secret|token|password|timeout" <source-and-config-paths>
+rg -ni "@.*Listener|new.*Client|builder\(|System\.getenv|ConfigurationProperties|Value\(" <source-and-config-paths>
+```
+
+Do not hard-code environment-dependent endpoints, resource names, identifiers,
+credentials, ACLs, or operational switches in annotations, constants, or
+business code. Stable protocol constants may remain code constants only when
+the design proves they are not environment-specific and no server-side
+resource must be provisioned. Test auto-creation, a successful local startup,
+or an already-existing test resource is not evidence that production is
+ready. Every server-side resource must have an explicit production owner,
+creation timing, readiness check, and rollback path. Missing production
+provisioning evidence is a blocker.
+
+## Concurrency And Idempotency Ownership
+
+批量开通、批量续费、并发请求、重复回调、重复消费或重复外部下发时必须填写。
+
+| 场景 | 业务幂等键 | 原子占用 owner/资源 | 应用层原子占用操作 | 短事务边界 | 状态流转 | 重试复用编码 | 外部调用边界 | 结果不确定处理 | 唯一索引角色 | 测试证据 |
+| ---- | ---------- | ------------------- | ------------------ | ---------- | -------- | ------------ | ------------ | -------------- | ------------ | -------- |
+| `<批量下发>` | `<套餐+车辆+周期>` | `<周期记录>` | `<锁定 owner 后写 PENDING>` | `<独立事务提交占用>` | `PENDING/SUCCESS/FAILED` | `<复用原业务单号>` | `<提交后调用>` | `<阻止重复并进入对账>` | `<非默认；必要时兜底>` | `<并发/重复/重试用例>` |
+
+应用层原子占用是默认方案：先用稳定业务幂等键在短事务内锁定明确的 owner 资源，
+写入 `PENDING` 并提交，再释放数据库锁后执行外部调用。外部调用成功或失败后更新
+状态；重试必须复用原业务单号。结果不确定时必须阻止重复下发并保留人工对账入口。
+禁止用“先查再插”、单进程锁或随机单号冒充跨实例幂等，也禁止在外部调用期间持有
+长事务或数据库锁。唯一索引不是默认方案；仅当自然唯一语义、历史数据清理、NULL/
+软删除行为和冲突处理合同都已明确时，才可作为数据库兜底。
+
 ## Field And Status Reverse Impact
 
 Use this whenever changing field values, enum/status values, derived fields,

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

@@ -166,6 +166,16 @@ HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are ski
 ## 9. 结论
 
 [是否达到交付标准，是否可以进入下一阶段]
+
+验证结果: PASS / FAIL / BLOCKED / PARTIALLY_VERIFIED
+归档就绪: PASS / BLOCKED
+
+`verify_mode: full` 时必须填写：
+
+- 测试环境：
+- 分支/commit/构建号或镜像：
+- Base URL：
+- 验证时间：
 ```
 
 ## 任务完成 Checklist（全部满足才能标记完成）