@chenmk/superflow 0.2.4 → 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,22 +54,63 @@ 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. Record state:
+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,
+   settlement/display-state fields, rounding boundary, scale, rounding mode,
+   allocation/reconciliation rule, and tests covering half-cent or residual
+   cases. If the design rounds money before later slicing, proration,
+   aggregation, discounting, or allocation, stop and redesign the calculation
+   boundary. When an additive identity has an authoritative total, the design
+   must calculate only N-1 components independently and derive the final
+   complement as `authoritative total - sum(other components)`. Independently
+   calculating and rounding all components before rebuilding the total is
+   blocked. A claimed exception must name the actual source of truth and owner
+   evidence. Read
+   `../superflow-pipeline/references/money-precision-algorithms.md` and also
+   freeze the exact representation, currency/minor-unit boundary, rounding
+   level and policy source, deterministic residual strategy with stable
+   tie-breaker, and positive/zero/negative evidence. For FX changes, freeze the
+   directional rate metadata and one canonical conversion path.
+11. Record state:
    ```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
@@ -77,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.
-10. 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
@@ -85,6 +96,17 @@ Binding` with:
 不确定项/阻塞处理 | 测试证据`. Unconfirmed values are blockers; do not
   invent numeric values, origin/source values, display meanings, or fallback
   mappings.
+- 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
+  declare `Money Precision Boundary` as blocking. `tests.md` and the
+  `test-report.md` skeleton must reserve half-cent, residual, or multi-detail
+  cases and reconciliation evidence. Do not freeze docs that allow intermediate
+  money to be rounded before later slicing, aggregation, discounting, or
+  allocation. For additive identities, docs must name the authoritative total,
+  independently calculated N-1 components, and the final complement formula:
+  `authoritative total - sum(other components)`. Do not allow every component
+  to be calculated and rounded independently before rebuilding the total.
 - For low-freedom implementation handoff, docs include the five hard gates:
   field semantic contract, write-through persistence closure, real-entry call
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
@@ -302,6 +324,11 @@ test-report证据位置`.
   `RED 失败证据`, `GREEN 通过证据`, `接口自动化证据`, `DB 核查证据`,
   `日志核查证据`, `未自动化/阻塞用例`, and `Partially verified 边界`.
   Each section must reference concrete `tests.md` case IDs.
+- For money-related changes, `test-report.md` must also include `Money Precision
+  Boundary` evidence: original calculation inputs and precision, actual rounding
+  boundary and mode, half-cent/residual/multi-detail cases, and reconciliation
+  of original, discount, actual/refund, and allocated totals. Evidence must show
+  which total was authoritative and which complement was derived by subtraction.
 - `sdd-quality-gate.md` must include blocking checks for:
   executable tests frozen, RED/GREEN expectations present, interface automation
   commands present, DB/log assertions present, and mock/skipped cases excluded

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

@@ -111,6 +111,23 @@ Before implementation phase can exit:
   source, Mapper XML, entities, DTO/VO, SQL, scheduled jobs, MQ/event consumers,
   callbacks, third-party adapters, shared SDK/tables, and sibling repos when
   applicable. A prompt that only changes the direct setter/writer is blocked.
+- When a task changes money, fees, discounts, deductions, refunds, sharing,
+  payments, invoices, balances, electricity/service fees, package settlement,
+  proration, allocation, reconciliation, or financial display, every prompt
+  must include "金额精度边界继承". It must copy the technical design
+  `Money Precision Boundary`, keep calculation-state precision until the
+  confirmed settlement/display boundary, forbid early `setScale(2)` before
+  later slicing or aggregation, and require deterministic residual allocation.
+  For additive identities with an authoritative total, the prompt must compute
+  only N-1 components independently and derive the final complement as
+  `authoritative total - sum(other components)`; calculating and rounding all
+  components independently is blocked.
+  It must inherit `money-precision-algorithms.md`: exact decimal construction,
+  currency/provider minor units, rounding level and policy source,
+  deterministic residual tie-breaker, pre/post-round audit, signed-value tests,
+  and conditional FX metadata.
+  RED/GREEN coverage must include half-cent, residual, or multi-detail cases
+  and prove reconciliation identities in `test-report.md`.
 - Every implementation prompt must include a "上下文防漂移与状态继承" section.
   It must link `.sdd/handoff/sdd-context.md` as a clickable Markdown link,
   record the exact `handoff_hash`, and require Worker/Tester/Reviewer to read

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
 
 ### 上下文防漂移与状态门禁（阻塞级）
@@ -402,6 +431,23 @@ SDD 设计、评审、实现 prompt 和测试报告中，字段/状态/枚举/
 - 兜底让异常数据、缺失字段、旧错误状态静默通过，且没有暴露机制，阻塞。
 - 无法证明字段值符合业务语义时，必须标记 `Blocked`，不得冻结设计或生成实现 prompt。
 
+### 金额精度边界门禁（阻塞级）
+
+凡涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、服务费、
+套餐结算、比例分摊、明细分配、对账或财务展示，必须从 docs、技术详设、实现
+prompt、代码评审、测试到 verify 继承同一份 `Money Precision Boundary`。
+
+- 最终结算/持久化/支付/开票/导出/展示边界前保留计算态原始精度。
+- 禁止提前 `setScale(2)` 后继续切片、分摊、汇总、抵扣或反推单价。
+- 多明细必须用确定性规则处理尾差，分配合计必须等于目标金额。
+- 存在加法恒等式且总额是真源时，只允许独立计算 N-1 个组成项；最后一个组成项
+  必须按 `权威总额 - 其余组成项合计` 差额反推。禁止所有组成项分别计算、分别
+  舍入后再相加重建权威总额。
+- tests.md 和 test-report.md 必须覆盖半分、尾差或多明细场景，并证明原始金额、
+  优惠金额、实付/退款金额和分配合计满足合同恒等式。
+- 缺少权威总额、差额反推公式、舍入边界、scale/rounding mode、分配规则或对账
+  证据时标记 `Blocked`。不适用差额反推时必须写明真实真源和 owner 证据。
+
 ### 低自由度研发 Agent 五项硬门禁（阻塞级）
 
 面向低能力或高自由发挥风险的研发 agent，SDD 文档必须把可猜测空间压到最低。
@@ -828,6 +874,7 @@ Load only the reference needed for the current phase:
 - OpenSpec format: `references/openspec-format.md`
 - Document quality: `references/quality-standards.md`
 - Quality gate: `references/quality-gate.md`
+- 金额精度算法基线：`references/money-precision-algorithms.md`
 - Batch prompt split: `references/batch-split-guide.md`
 - Batch prompt template: `references/batch-prompt-template.md`
 - Implementation orchestration: `references/orchestration.md`

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,50 @@ 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/软删除和冲突合同明确后才可
+作为数据库兜底。结果不确定时必须阻止重复调用并进入可追踪对账。
+
+## 金额精度边界继承（强制）
+
+如果本批涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、
+服务费、套餐结算、比例分摊、明细分配、对账或财务展示，必须从 Superpowers
+技术详设复制 `Money Precision Boundary`。
+
+| 恒等式/权威总额 | 精确类型/构造 | 币种/渠道最小单位 | 舍入层级/mode/来源 | 分配策略/tie-breaker | 差额反推 | 审计证据 | 正负边界测试 |
+| ---------------- | ------------- | ----------------- | -------------------- | --------------------- | -------- | -------- | ------------ |
+| 原始=优惠+实付/原始金额 | BigDecimal/字符串 | CNY/最小单位 | 整单/HALF_UP/合同 | 最大余数/业务主键 | 实付=原始-优惠 | 舍入前后/尾差接收方 | 半分/尾差/退款 |
+
+中间计算不得提前舍入后继续切片、分摊、汇总或抵扣；多明细必须确定性处理尾差，
+并在 test-report.md 证明原始金额、优惠金额、实付金额和分配合计满足合同恒等式。
+存在权威总额时，只独立计算 N-1 个组成项，最后一个组成项按权威总额减去其余
+组成项合计差额反推；禁止所有组成项分别计算、分别舍入后重建总额。必须继承
+`money-precision-algorithms.md` 的币种单位、舍入来源、稳定排序、负数对称和条件性
+汇率合同。
+
 ## SDD 门禁激活（第一步，在所有编码工作之前执行）
 
 本机已配置 Codex Hooks，会在 Edit/Write 时自动拦截。你必须按以下顺序激活：

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

@@ -148,6 +148,54 @@ Superpowers 技术详设复制 `外部枚举绑定确认` / `External Enum Bindi
 禁止用请求成功、值非空或字段存在替代外部枚举业务语义确认。未确认的外部枚举、
 支付来源、财务展示含义或兜底映射，必须停止并报告 `Blocked`。
 
+### 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
+技术详设复制 `Money Precision Boundary`，并在编码前填写：
+
+| 恒等式/权威总额 | 精确类型/构造 | 币种/内部与渠道单位 | 舍入层级/scale/mode/来源 | 分配策略/稳定 tie-breaker | 差额反推公式 | 舍入前后/尾差接收方 | 正数/零/退款测试 |
+| ---------------- | ------------- | ------------------- | ------------------------- | ------------------------- | ------------ | --------------------- | ---------------- |
+| 原始=优惠+实付/原始金额 | BigDecimal/字符串 | CNY/计算 scale/最小单位 | 整单/2/HALF_UP/合同 | 最大余数/业务主键 | 实付=原始-优惠 | \_\_\_\_ | TC-\_\_\_\_ |
+
+计算态必须保留原始费率、数量、乘积、比例和分配精度，只能在已确认的结算、
+持久化、支付、开票、导出或展示边界统一舍入。禁止先 `setScale(2)` 再继续切片、
+分摊、汇总、抵扣或反推单价。多明细分配必须确定性处理尾差，并证明原始金额、
+优惠金额、实付金额和分配合计满足合同恒等式。存在加法恒等式且总额是真源时，
+只能独立计算 N-1 个组成项，最后一个组成项必须按“权威总额减去其余组成项合计”
+差额反推；禁止所有组成项分别计算、分别舍入后再相加重建权威总额。缺少证据时
+停止并报告 `Blocked`。同时读取 `money-precision-algorithms.md`；禁止默认所有币种
+两位小数、从 `double` 构造金额或用数据库隐式舍入代替业务合同。汇率场景还要
+继承 base/quote、汇率来源与时间、唯一换算路径及目标结算单位。
+
 ### 2. 写入闭环
 
 凡本批涉及回填、落库、绑定、持久化、快照、同步、状态推进，必须填写：