@chenmk/superflow 0.5.11 → 0.5.13

package/assets/scripts/superflow-sql-sync-hook.py

@@ -5,6 +5,11 @@ SDD SQL sync hook.
 Warns when database-backed Java/XML changes are made without a version-level
 summary SQL change. Blocks forbidden migration SQL style before commit.
 
+Hook registration note: this hook is intentionally registered twice
+(default matcher + Bash matcher override). The default matcher covers SQL
+file edits; the Bash matcher covers git commit paths. Both trigger surfaces
+need the SQL sync check -- do not "fix" this as a duplicate registration.
+
 Forbidden (B1-B8, blocks commit):
 - B1 ALTER TABLE ADD COLUMN IF NOT EXISTS
 - B2 CREATE [UNIQUE] INDEX IF NOT EXISTS
@@ -59,12 +64,27 @@ per finding for the developer to apply):
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 from pathlib import Path
 
+# Defensive short-circuit: run SDD gates only in SDD projects
+# (openspec/, .sdd/, .sdd-enforced); zero-cost exit elsewhere.
+if not (os.path.isdir('openspec') or os.path.isdir('.sdd') or os.path.isfile('.sdd-enforced')):
+    raise SystemExit(0)
+
 
 DB_CODE_FILE = re.compile(r"\.(java|xml)$", re.I)
+MYBATIS_SAFE_EXPRESSIONS = frozenset({
+    "ew.sqlSegment", "ew.customSqlSegment", "ew.sqlSet", "ew.sqlComment",
+})
+MYBATIS_INTERPOLATION = re.compile(r"\$\{([^}]+)\}")
+SECRET_PATTERNS = (
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    re.compile(r"\b(?:api[_-]?key|api[_-]?secret)\s*[:=]\s*['\"][^'\"]{8,}", re.I),
+    re.compile(r"\b[a-z_][a-z0-9_]*_(?:secret|token)\s*[:=]\s*['\"][^'\"]{16,}['\"]", re.I),
+)
 SQL_SUMMARY_FILE = re.compile(r"(^|/)sql/.*\.sql$", re.I)
 NO_SQL_ACK_FILE = re.compile(
     r"(^|/)(openspec/.*\.(md|yaml|yml)|ReleaseNotes\.md)$",
@@ -504,10 +524,113 @@ def warn(message, block=False):
     print(f"[SDD SQL 收口{prefix}] {message}", file=sys.stderr)
 
 
+def mapper_interpolations(file_path, content):
+    normalized = file_path.replace("\\", "/")
+    if not normalized.lower().endswith(".xml"):
+        return []
+    mapper_path = re.search(r"(?:^|/)(?:mapper|dao)/", normalized, re.I)
+    mapper_name = re.search(r"(?:Mapper|Dao)\.xml$", normalized)
+    mapper_body = re.search(r"<mapper\b|<!DOCTYPE\s+mapper", content, re.I)
+    if not (mapper_path or mapper_name or mapper_body):
+        return []
+    return [match.group(1).strip() for match in MYBATIS_INTERPOLATION.finditer(content)
+            if match.group(1).strip() not in MYBATIS_SAFE_EXPRESSIONS]
+
+
+def git_segment_args(segment):
+    tokens = shlex.split(segment)
+    git_at = next((i for i, token in enumerate(tokens)
+                   if token == "git" or token.endswith("/git")), -1)
+    if git_at < 0:
+        return None
+    return tokens[:git_at], tokens[git_at + 1:]
+
+
+def git_subcommand_index(args):
+    index = 0
+    while index < len(args) and args[index].startswith("-"):
+        index += 2 if args[index] in ("-c", "-C") else 1
+    return index
+
+
+def check_git_bypass(command):
+    for segment in re.split(r"\|\||&&|[;|\n]", command):
+        try:
+            parsed = git_segment_args(segment)
+        except ValueError:
+            if "git" in segment and ("--no-verify" in segment or "core.hooksPath" in segment):
+                return "Git 命令无法解析且包含 Hook 绕过参数"
+            continue
+        if parsed is None:
+            continue
+        prefix, args = parsed
+        config_override = any(
+            arg.startswith("core.hooksPath=") for arg in args
+        ) or any(token.startswith("GIT_CONFIG_") and "core.hooksPath" in token
+                 for token in prefix)
+        if config_override or "--no-verify" in args:
+            return "禁止使用 --no-verify 或 core.hooksPath 绕过 Git Hook"
+        index = git_subcommand_index(args)
+        if index < len(args) and args[index] == "commit":
+            flags = []
+            skip_value = False
+            for arg in args[index + 1:]:
+                if skip_value:
+                    skip_value = False
+                    continue
+                if arg in ("-m", "--message", "-F", "--file"):
+                    skip_value = True
+                    continue
+                flags.append(arg)
+            if any(re.fullmatch(r"-[a-zA-Z]*n[a-zA-Z]*", arg)
+                   for arg in flags):
+                return "禁止使用 git commit -n 绕过 Git Hook"
+    return None
+
+
+def is_git_commit(command):
+    for segment in re.split(r"\|\||&&|[;|\n]", command):
+        try:
+            parsed = git_segment_args(segment)
+        except ValueError:
+            continue
+        if parsed is None:
+            continue
+        _, args = parsed
+        index = git_subcommand_index(args)
+        if index < len(args) and args[index] == "commit":
+            return True
+    return False
+
+
+def check_staged_secrets(root):
+    result = run(["git", "diff", "--cached", "--unified=0", "--no-ext-diff"], cwd=root)
+    if result.returncode != 0:
+        return []
+    findings = []
+    current_path = ""
+    for line in result.stdout.splitlines():
+        if line.startswith("+++ b/"):
+            current_path = line[6:]
+        elif line.startswith("+") and not line.startswith("+++"):
+            if any(pattern.search(line[1:]) for pattern in SECRET_PATTERNS):
+                findings.append(current_path)
+    return sorted(set(findings))
+
+
 def handle_commit(command, root):
-    if not re.search(r"\bgit\s+commit\b", command):
+    bypass = check_git_bypass(command)
+    if bypass:
+        warn(bypass, block=True)
+        return 2
+    if not is_git_commit(command):
         return 0
 
+    secrets = check_staged_secrets(root)
+    if secrets:
+        warn("暂存差异包含疑似硬编码密钥：" + ", ".join(secrets), block=True)
+        return 2
+
     files = staged_files(root)
     if not files:
         return 0
@@ -585,6 +708,11 @@ def handle_commit(command, root):
 def handle_edit(file_path, edit_content):
     if not file_path:
         return 0
+    unsafe = mapper_interpolations(file_path, edit_content)
+    if unsafe:
+        warn("Mapper XML 使用危险 ${} 插值：" + ", ".join(unsafe[:3])
+             + "；请使用 #{}，动态标识符须在 Java 侧白名单校验。", block=True)
+        return 2
     if SQL_SUMMARY_FILE.search(file_path):
         sql_style_issues = lint_sql_style(file_path, edit_content)
         if sql_style_issues:
@@ -934,7 +1062,9 @@ def main():
 
     start = Path.cwd()
     if file_path:
-        start = Path(file_path).expanduser().resolve().parent
+        candidate = Path(file_path).expanduser().resolve().parent
+        if candidate.exists():
+            start = candidate
     root = repo_root(start)
     if root is None:
         return 0
@@ -942,7 +1072,25 @@ def main():
     if command:
         return handle_commit(command, root)
 
-    edit_content = tool_input.get("new_string") or tool_input.get("content") or ""
+    patch = tool_input.get("patch") or ""
+    if patch:
+        sections = re.split(r"(?=^\*\*\* (?:Add|Update) File: )", patch, flags=re.M)
+        for section in sections:
+            target = re.search(r"^\*\*\* (?:Add|Update) File: (.+)$", section, re.M)
+            if not target:
+                continue
+            added = "\n".join(line[1:] for line in section.splitlines()
+                              if line.startswith("+") and not line.startswith("+++"))
+            if handle_edit(target.group(1), added) == 2:
+                return 2
+        return 0
+
+    edits = tool_input.get("edits")
+    if isinstance(edits, list):
+        edit_content = "\n".join(str(edit.get("new_string") or "")
+                                 for edit in edits if isinstance(edit, dict))
+    else:
+        edit_content = tool_input.get("new_string") or tool_input.get("content") or ""
     return handle_edit(file_path, edit_content)
 
 

package/assets/skill-registry.json

@@ -0,0 +1,229 @@
+{
+  "version": "1.0.0",
+  "contracts": [
+    {
+      "name": "openspec-apply-change",
+      "owner": "implement",
+      "triggers": [
+        "implement approved change"
+      ],
+      "excludes": [],
+      "outputs": [
+        "tasks.md progress"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "openspec-archive-change",
+      "owner": "archive",
+      "triggers": [
+        "archive completed change"
+      ],
+      "excludes": [],
+      "outputs": [
+        "archive result"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "openspec-explore",
+      "owner": "explore",
+      "triggers": [
+        "explore requirements"
+      ],
+      "excludes": [],
+      "outputs": [
+        "alignment.md"
+      ],
+      "neighbors": [
+        "openspec-propose"
+      ]
+    },
+    {
+      "name": "openspec-propose",
+      "owner": "propose",
+      "triggers": [
+        "generate OpenSpec proposal"
+      ],
+      "excludes": [],
+      "outputs": [
+        "proposal.md specs design.md tasks.md"
+      ],
+      "neighbors": [
+        "superflow-clarify",
+        "superflow-design",
+        "superflow-implement"
+      ]
+    },
+    {
+      "name": "superflow-archive",
+      "owner": "archive",
+      "triggers": [
+        "archive SDD change"
+      ],
+      "excludes": [],
+      "outputs": [
+        "archive report"
+      ],
+      "neighbors": [
+        "superflow-verify"
+      ]
+    },
+    {
+      "name": "superflow-clarify",
+      "owner": "clarify",
+      "triggers": [
+        "clarify requirements"
+      ],
+      "excludes": [],
+      "outputs": [
+        "source-code-audit.md feature-gates.md brainstorm-summary.md"
+      ],
+      "neighbors": [
+        "openspec-propose",
+        "superflow-docs"
+      ]
+    },
+    {
+      "name": "superflow-design",
+      "owner": "design",
+      "triggers": [
+        "technical design"
+      ],
+      "excludes": [],
+      "outputs": [
+        "technical_design"
+      ],
+      "neighbors": [
+        "superflow-docs",
+        "superflow-implement"
+      ]
+    },
+    {
+      "name": "superflow-docs",
+      "owner": "docs",
+      "triggers": [
+        "SDD contract documents"
+      ],
+      "excludes": [],
+      "outputs": [
+        "api.md tests.md sdd-quality-gate.md"
+      ],
+      "neighbors": [
+        "superflow-clarify",
+        "superflow-design",
+        "superflow-implement"
+      ]
+    },
+    {
+      "name": "superflow-hotfix",
+      "owner": "pipeline",
+      "triggers": [
+        "urgent small fix"
+      ],
+      "excludes": [],
+      "outputs": [
+        "bug-fix-plan.md"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-implement",
+      "owner": "implement",
+      "triggers": [
+        "generate implementation prompts"
+      ],
+      "excludes": [],
+      "outputs": [
+        "prompt/ test-report.md"
+      ],
+      "neighbors": [
+        "superflow-design",
+        "superflow-verify"
+      ]
+    },
+    {
+      "name": "superflow-pipeline",
+      "owner": "pipeline",
+      "triggers": [
+        "Superflow SDD pipeline"
+      ],
+      "excludes": [],
+      "outputs": [
+        "state.yaml handoff"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-requirement-review",
+      "owner": "review",
+      "triggers": [
+        "review requirements"
+      ],
+      "excludes": [],
+      "outputs": [
+        "requirement-review.md"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-table-impact-analysis",
+      "owner": "docs",
+      "triggers": [
+        "table impact analysis"
+      ],
+      "excludes": [],
+      "outputs": [
+        "impact analysis"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-tweak",
+      "owner": "pipeline",
+      "triggers": [
+        "small wording tweak"
+      ],
+      "excludes": [],
+      "outputs": [
+        "tweak result"
+      ],
+      "neighbors": []
+    },
+    {
+      "name": "superflow-quick-dev",
+      "owner": "quick",
+      "triggers": [
+        "small code task",
+        "quick development"
+      ],
+      "excludes": [
+        "public API or database change",
+        "cross-module change"
+      ],
+      "outputs": [
+        ".sdd/tasks/<date>-<slug>/spec.md",
+        "quick evidence"
+      ],
+      "neighbors": [
+        "superflow-clarify",
+        "superflow-verify"
+      ]
+    },
+    {
+      "name": "superflow-verify",
+      "owner": "verify",
+      "triggers": [
+        "verify implementation"
+      ],
+      "excludes": [],
+      "outputs": [
+        "verification report"
+      ],
+      "neighbors": [
+        "superflow-implement",
+        "superflow-archive"
+      ]
+    }
+  ]
+}

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

@@ -22,6 +22,14 @@ When ready to implement, run /opsx:apply
 
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
+When this skill follows `superflow-clarify`, read the confirmed change-level
+Consensus Summary and its source evidence before creating artifacts. Put the
+goal, scope, material owner decisions, rejected alternatives, migration risks,
+and non-blocking reopen triggers in canonical `proposal.md`; cite the existing
+source audit rather than copying it. A pending owner decision that changes the
+solution blocks downstream spec/design/tasks. An explicit decision in the
+user's original request needs no second confirmation.
+
 ### OpenSpec canonical change 目录（阻塞级）
 
 - change 必须只有一个实体目录：`openspec/changes/<name>/`。
@@ -108,6 +116,12 @@ After completing all artifacts, summarize:
 - Follow the `instruction` field from `openspec instructions` for each artifact type
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
+- For a Superflow change, keep ordinary OpenSpec checkbox task syntax. For each
+  independently verifiable task, state its observable delivery and acceptance
+  signal; record real predecessor task IDs as `Blocked by` and link the relevant
+  requirement/scenario or traceability row. A free-text blocker does not change
+  Superflow's `[local_required]` / `[environment_required]` /
+  `[release_required]` machine classification. Do not invent dependencies.
 - Use `template` as the structure for your output file - fill in its sections
 - **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
   - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact

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

@@ -13,7 +13,7 @@ any full SDD document or implementation prompt is generated.
 
 - Before freezing any new requirement or bug fix, perform platform-level impact
   discovery. Prefer understand-anything artifacts when present, such as
-  `.understand-anything/`, `understand-anything.md`, `understand anything.md`,
+  `.ua/`, `.understand-anything/`, `understand-anything.md`, `understand anything.md`,
   or the project-specific graph output, but treat them only as locator evidence.
   If artifacts are missing, stale, incomplete, or unavailable, degrade to `rg`,
   source reading, Mapper/XML, configuration, database table names, log
@@ -171,6 +171,28 @@ Use the detailed workflow in:
     indexed feature. Do not batch-confirm multiple features from memory or a
     compressed chat summary.
 
+### Change-level alignment before OpenSpec artifacts
+
+After all in-scope features are frozen, present one concise change-level
+`Consensus Summary` covering the goal, in/out scope, verified source facts,
+owner decisions with rejected alternatives, production and migration risks,
+and remaining non-blocking questions with owner and reopen trigger. Derive it
+from `source-code-audit.md`, `feature-gates.md`, and the confirmed decisions in
+`.sdd/handoff/brainstorm-summary.md`; the summary is a handoff view, not a
+second source of requirements. Record unresolved decisions as blockers and
+ask only the next owner decision. Do not ask the user to reconfirm facts or
+choices already explicit in the original request.
+
+When a material owner choice was made during clarification, show the current
+summary before generating OpenSpec artifacts. Reuse an explicit confirmation
+already given for that exact choice and summary; ask once only if the summary
+introduces a new choice or changes its consequence. The later `proposal.md`
+must carry the confirmed change-level
+decisions and cite their evidence. If a later finding changes a confirmed
+choice, return to that decision, update affected canonical documents, refresh
+the handoff hash and repeat document review and Coding Ready. Task checkbox
+progress alone does not change the agreed contract.
+
 ## Handoff
 
 When the feature is frozen, tell the user to continue with `$openspec-propose`

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

@@ -64,7 +64,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 5. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-6. Complete `复杂度减法评审` before expanding source-level HOW. For every new
+6. For each new or changed module interface, add a `Design-It-Twice` card to
+   the technical design: two materially different interfaces, seam and adapter
+   ownership, the real test surface, reuse evidence, caller consequences, and
+   an explicit choice. Renaming the same interface does not count as two
+   options; revisit it. This card is advisory and does not add a state gate.
+7. Complete `复杂度减法评审` before expanding source-level HOW. For every new
    table, field, API, Service/component, abstraction, cache, async/MQ/event
    flow, scheduled job, or compatibility layer, prove existing reuse options,
    necessity, and why the simplest direct implementation is insufficient.

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

@@ -37,6 +37,12 @@ Do not invent new fields or requirements.
 
 For complex requirements, verify these before writing docs:
 
+- `proposal.md` carries the confirmed change-level Consensus Summary from
+  clarification: goal, scope, owner choices and rejected alternatives,
+  production/migration risks, and non-blocking reopen triggers. Check it
+  against original sources and `source-code-audit.md`; do not treat the
+  handoff summary as a second authority. If a material choice remains open,
+  return to `$superflow-clarify` before finalizing design or tasks.
 - `source-ingestion.md`, `feature-inventory.md`, and `feature-gates.md` prove
   that the original PRD/Lark/Feishu/screenshots were processed section by
   section, not summarized into tasks in one whole-document pass. Each feature
@@ -240,6 +246,12 @@ applicable:
 - `tasks.md` 每个 checkbox 必须带且只带一个机器分类：`[local_required]`、
   `[environment_required]` 或 `[release_required]`。能够在本地完成的编码、测试、启动和浏览器
   验证必须是 local_required；不得用自由文本 Blocker/owner 代替分类。
+- For each implementation task, review observable delivery, acceptance signal,
+  requirement/scenario coverage, and actual predecessors. Show the currently
+  executable tasks whose predecessors are complete. Reuse
+  `traceability-matrix.md` for detailed coverage; do not create another task
+  state file. `Blocked by` expresses execution order and never changes the
+  machine task classification above.
 - `tests.md`
 - `test-report.md` skeleton
 - `sdd-quality-gate.md`

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

@@ -83,6 +83,14 @@ Before implementation phase can exit:
 ## Prompt Splitting Rules
 
 - Split by independently verifiable feature closure, not by a giant backend module.
+- Read `tasks.md` predecessor links before splitting or dispatching. A batch is
+  executable only when its real predecessors are complete; independent batches
+  may run in parallel. Keep the existing checkbox and machine category as the
+  progress authority. An implementation discovery that changes a confirmed
+  owner decision or task acceptance requires canonical document repair,
+  handoff refresh, document review, and a new Coding Ready receipt before the
+  affected batch resumes. A free-text `Blocked by` note cannot downgrade a
+  locally executable task to an external category.
 - Use P0 for baseline only: worktree, branch, compile, SQL/entity/mapper/DTO consistency.
 - Keep business prompts small and explicit.
 - Every implementation prompt must begin with the mandatory superpower/team

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

@@ -7,6 +7,16 @@ description: SDD 总入口和路由技能。Use when the user says sdd, SDD 流
 
 This is the lightweight SDD router. Do not load the whole SDD process when a smaller phase skill is enough.
 
+## 角色 owner 与互斥边界
+
+| 角色 | 唯一 owner | 可以做 | 不可以做 |
+|---|---|---|---|
+| Host | 目标、澄清、监督、语义评审 | 选择路由、判断代码/架构风险、决定是否接受反馈 | 代替 Executor 写业务代码；启动嵌套 Supervisor |
+| Executor | 源码实现、测试、启动、整改 | 在冻结合同内修改工作区并提交证据 | 改合同/状态；自行降低验收等级；自动提交发布 |
+| Runner | 状态、哈希、退出码、证据持久化 | 调度、等待、恢复、确定性门禁 | 猜业务语义；重新设计 API/DB；代替 Host 评审 |
+
+菜单或 persona 只改变入口表达，不创建第二套状态机；发现 owner 冲突时回到 Host 澄清。
+
 维护 Superflow CLI 自身时，必须先读取仓库根目录
 `docs/superflow-cli-design-principles.md` 和
 `docs/superflow-cli-evaluation-framework.md`；涉及托管时再读取托管专项宪章与协议。
@@ -86,6 +96,12 @@ JSON，再用 `--resume-task <task-id> --submit-host-review <json>` 恢复。监
 
 ## Choose The Right SDD Skill
 
+- Use `$superflow-quick-dev` for one clear, low-blast-radius code change along
+  an existing test seam. Run its narrow gate before editing; API, DB, security,
+  transactions, concurrency, payments, cross-module work, a related active SDD
+  change, or uncertain ownership goes to `$superflow-clarify` instead. Reuse
+  the current quick managed profile after the Quick Spec is approved; do not
+  create a second managed-task state machine.
 - 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
@@ -163,6 +179,12 @@ When the router selects embedded deep clarification, follow these rules inside
 - 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.
+- After all relevant features are frozen, show the change-level Consensus
+  Summary from `superflow-clarify` before OpenSpec artifact generation. Carry
+  confirmed choices into canonical `proposal.md`; do not create a parallel
+  alignment fact source or add approval prompts for decisions already explicit
+  in the user's request. A changed owner choice requires affected documents,
+  handoff, review, and Coding Ready to be refreshed before execution.
 
 ## Non-Negotiable Rules
 
@@ -326,6 +348,11 @@ context_compression | created_at | verified_at | updated_at`
 
 - 设计范围、API/DB 合同、执行模式、验证边界、archive closeout 需要用户取舍时，
   使用 `references/decision-point.md` 的格式记录，不用聊天记忆代替。
+
+仓库级术语或持久架构决定可运行 `superflow context-audit --path <project>`
+做只读检查。业务术语放入 `CONTEXT.md`；只有难逆转且存在有意义备选方案时才写 ADR。
+审计是 advisory：缺少 ADR 只提醒，ADR 字段不全或术语混入实现细节才报告修复项，
+不新增审批门禁，也不替代 `design.md`。
 - 脏工作区、并行 worktree 或跨会话接力前，使用 `references/dirty-worktree.md`
   的检查项，避免覆盖用户改动或拿旧 handoff 继续。
 - `build_mode: subagent-driven-development` 时，维护
@@ -431,7 +458,7 @@ Mapper/XML、数据库样例、接口契约和真实消费入口验证。
 **影响面发现方式（优先但可降级）：**
 
 - 优先检查当前仓库是否存在 understand-anything 相关索引/产物，例如
-  `.understand-anything/`、`understand-anything.md`、`understand anything.md`、
+  `.ua/`、`.understand-anything/`、`understand-anything.md`、`understand anything.md`、
   或项目约定的 understand-anything 图谱文件。
 - 如果索引存在，可以用它快速定位整个平台相关代码，包括当前仓库、同平台
   sibling repo、共享 SDK、公共 DTO、数据库表消费方、定时任务、回调入口、外部平台

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

@@ -20,6 +20,23 @@ canonical_sources:
 
 # Superpowers Technical Design: <change title>
 
+## Design-It-Twice：接口与 seam 选择
+
+仅在新增或改变模块接口时填写；纯实现内重构可写“无接口变化”。
+
+| 项目 | 方案 A | 方案 B |
+|---|---|---|
+| 接口与调用方约束 |  |  |
+| seam 与 adapter owner |  |  |
+| 真实测试面 |  |  |
+| 复用证据（文件/符号） |  |  |
+| 爆炸半径与后果 |  |  |
+
+- 选择：A / B
+- 选择理由：
+- 被拒绝方案的具体代价：
+- 两种方案不能只是改名或换参数顺序。
+
 ## Boundary
 
 - This document owns source-level HOW only.