@chenmk/superflow 0.2.5 → 0.3.0

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

@@ -178,6 +178,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 +313,28 @@ change_has_external_enum_risk() {
     "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
 }
 
+change_has_external_config_risk() {
+  grep -RIEiq \
+    '第三方|外部平台|外部工具|外部集成|third[- ]party|external (platform|tool|integration|system)|SDK|MQ|Kafka|RocketMQ|TDMQ|callback|回调|webhook|支付渠道|payment gateway|cloud service|云服务' \
+    "$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_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' \
@@ -325,6 +401,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"
@@ -412,6 +515,13 @@ case "$PHASE" in
       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
@@ -450,6 +560,12 @@ 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
@@ -481,6 +597,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 +625,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 +635,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 +658,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/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

@@ -54,10 +54,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
+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 amount, fee, discount, deduction, refund, sharing, payment, invoice,
+9. 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 +98,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:
+10. 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
+11. 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 +111,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:
+12. 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

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

@@ -37,6 +37,11 @@ hotfix:
 
 ## Routing
 
+- When the user explicitly asks for rigorous questioning, or a bounded feature
+  has unresolved owner decisions, mutually exclusive approaches, an unclear
+  source of truth, unclear acceptance behavior, or cross-system responsibility,
+  use `superflow-clarify` in embedded deep-clarification mode. This is a mode
+  inside the normal clarify phase, not a separate command the user must remember.
 - New or unclear requirement: use superflow-clarify.
 - Confirmed requirement needing full docs: use openspec-propose, then
   superflow-docs.
@@ -49,6 +54,29 @@ hotfix:
 - Urgent small behavior repair: use superflow-hotfix, unless API, DB, cross-repo,
   status, SQL, SDK, or real-entry gates are involved.
 
+## 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.
+- Establish facts 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.
+
 ## Required Artifacts
 
 For a full change, the docs phase must create or refresh:

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

@@ -11,6 +11,14 @@ Use api.md as the canonical contract before implementation.
 - Frontend mapping: screen field, API field, DTO/VO field, DB field, test case.
 - External dependency contract: SDK version, topic/path, parameter source,
   sample request/response, timeout and retry behavior.
+- External Integration Configuration And Deployment Contract for third-party
+  platforms/tools, SDKs, MQ/Kafka, callbacks, payment providers, cloud
+  services, or other external integrations. Inventory endpoint,
+  app/tenant/project IDs, Topic/Tag/Consumer Group, namespace, webhook,
+  ACL/role, feature switches, timeout, and credential references for local,
+  test, and production; record injection/provisioning method, runtime owner,
+  provisioning owner/time, readiness evidence, rollback, secret handling, and
+  blockers.
 - File contract when upload/download/export is involved: Content-Type,
   Content-Disposition, filename rule, body format, frontend detection rule.
 - Compatibility and migration notes.
@@ -20,3 +28,8 @@ Use api.md as the canonical contract before implementation.
 
 Do not allow design, tasks, tests, or prompts to proceed if API changes are only
 summarized as core fields, same as existing endpoint, or to be added later.
+Environment-dependent external configuration and server-side resources must
+not exist only as hard-coded annotations, constants, or business code. Test
+auto-creation, existing historical resources, or successful local startup do
+not prove production readiness; missing production provisioning evidence
+blocks release.

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

@@ -24,6 +24,22 @@ review-checklist.md, sdd-quality-gate.md, test-report.md, and technical design.
 - Do not change forbidden files or root aggregate docs from a worker batch.
 - Use TDD: record RED failure before GREEN success.
 - Do not mark mock-only or unit-only evidence as real integration.
+- For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+  providers, cloud services, or other external integrations, inherit
+  `External Integration Configuration And Deployment Contract`. Cover
+  local/test/production sources and provisioning, injection/creation,
+  runtime/provisioning owners and timing, readiness evidence, rollback, secret
+  handling, and blockers. Do not hard-code environment-dependent values or
+  infer production readiness from test auto-creation.
+- For concurrent requests, batch issue/activation/renewal, duplicate callbacks
+  or consumption, and repeated external delivery, inherit `Concurrency And
+  Idempotency Ownership`. Define a stable business idempotency key,
+  application-layer atomic claim owner, short transaction boundary,
+  PENDING/SUCCESS/FAILED state machine, retry reuse of the original business
+  code, external-call boundary, and uncertain-result reconciliation. Release
+  database locks before external calls. A unique index is not the default and
+  may only be an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
 - For monetary changes, inherit `Money Precision Boundary`, retain
   calculation-state precision until the confirmed settlement/display boundary,
   record scale and rounding mode, forbid early rounding before slicing or

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

@@ -23,6 +23,23 @@ Superpowers technical design is canonical for source-level HOW and execution.
 - Field semantic contract checked.
 - Write-loop checked.
 - No-fallback boundary confirmed.
+- External Integration Configuration And Deployment Contract copied from the
+  API, quality gate, and technical design for third-party platforms/tools,
+  SDKs, MQ/Kafka, callbacks, payment providers, cloud services, or other
+  external integrations. Cover local/test/production sources and provisioning,
+  injection/creation, runtime/provisioning owners and timing, readiness
+  evidence, rollback, secret handling, and blockers. Do not hard-code
+  environment-dependent external values or treat test auto-creation as
+  production readiness evidence.
+- Concurrency And Idempotency Ownership copied from the technical design for
+  concurrent requests, batch issue/activation/renewal, duplicate callbacks or
+  consumption, and repeated external delivery. Define a stable business
+  idempotency key, application-layer atomic claim owner, short transaction
+  boundary, PENDING/SUCCESS/FAILED state machine, retry reuse of the original
+  business code, external-call boundary, and uncertain-result reconciliation.
+  Release database locks before external calls. A unique index is not the
+  default; it is only an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
 - Money Precision Boundary copied from the technical design when monetary
   behavior changes. Keep calculation-state precision until the confirmed
   settlement/display boundary, record scale and rounding mode, forbid early

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

@@ -16,6 +16,23 @@
 - Field/status reverse impact matrix exists when risky fields or states change.
 - Architecture boundary and call-direction matrix exists for cross-service or
   external flows.
+- External Integration Configuration And Deployment Contract exists for
+  third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment providers,
+  cloud services, or other external integrations. It inventories environment
+  sources and provisioning for endpoints, app/tenant/project IDs,
+  Topic/Tag/Consumer Group, namespace, webhook, ACL/role, switches, timeouts,
+  and credential references; names runtime/provisioning owners, timing,
+  readiness evidence, rollback, secret handling, and blockers; and forbids
+  environment-dependent hard-coded values. Test auto-creation, existing test
+  resources, or local startup do not prove production readiness.
+- Concurrency And Idempotency Ownership exists for concurrent requests, batch
+  issue/activation/renewal, duplicate callbacks/consumption, or repeated
+  external delivery. It defines the business idempotency key,
+  application-layer atomic claim owner, short transaction boundary,
+  PENDING/SUCCESS/FAILED state machine, retry code reuse, external-call
+  boundary, and uncertain-result reconciliation. A unique index is not the
+  default; it is only an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
 - Money precision boundary exists when amount, fee, discount, deduction,
   refund, sharing, payment, invoice, balance, electricity fee, service fee,
   package settlement, proration, allocation, reconciliation, or financial

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

@@ -59,6 +59,52 @@ 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
+
+Complete this section for concurrent requests, batch issue/activation/renewal,
+duplicate callbacks, duplicate consumption, or repeated external delivery.
+
+| Scenario | Business idempotency key | Claim owner/resource | Application-layer atomic claim | Short transaction boundary | State machine | Retry code reuse | External-call boundary | Uncertain-result handling | Unique-index role | Test evidence |
+| -------- | ------------------------ | -------------------- | ------------------------------ | -------------------------- | ------------- | ---------------- | ---------------------- | ------------------------- | ----------------- | ------------- |
+| `<batch issue>` | `<package+vehicle+period>` | `<period row>` | `<lock owner then persist PENDING>` | `<commit claim independently>` | `PENDING/SUCCESS/FAILED` | `<reuse original business code>` | `<call after commit>` | `<block duplicates and reconcile>` | `<not default; optional fallback>` | `<concurrent/duplicate/retry cases>` |
+
+Application-layer atomic claim is the default: use a stable business
+idempotency key, lock an explicit owner resource in a short transaction,
+persist `PENDING`, commit, and release the database lock before the external
+call. Update the state after the call; every retry reuses the original business
+code. An uncertain result blocks duplicate delivery and remains reconcilable.
+Do not use check-then-insert, process-local locks, or random IDs as cross-instance
+idempotency, and do not hold a database lock across an external call. A unique
+index is not the default; it is only an optional database fallback when natural
+uniqueness, historical cleanup, NULL/soft-delete behavior, and conflict handling
+are explicitly contracted.
+
 ## Field And Status Reverse Impact
 
 Use this whenever changing field values, enum/status values, derived fields,

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

@@ -38,3 +38,15 @@ rounded. Record currency, provider minor unit, pre/post-round values, residual
 recipient, and positive/zero/negative or refund, tied remainder, and idempotent
 recalculation evidence. FX cases also record base/quote, rate source, and target
 settlement rounding. A two-decimal display assertion alone is insufficient.
+
+## Closeout
+
+Verification Result: PASS / FAIL / BLOCKED / PARTIALLY_VERIFIED
+Archive Readiness: PASS / BLOCKED
+
+Required for `verify_mode: full`:
+
+- Test environment:
+- Branch/commit/build number or image:
+- Base URL:
+- Verification timestamp: