@chenmk/superflow 0.3.0 → 0.5.0

package/assets/skills/superflow-requirement-review/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: superflow-requirement-review
+description: 对已澄清或已形成 OpenSpec/SDD 草案的需求和设计执行源码驱动的反向评审，主动发现闭环缺口、事实冲突、遗漏场景、过度设计、欠设计、API/UI/DB/tests 漂移及不可验证合同，并推动整改和复审闭环。Use when the user asks for 需求评审、反向评审、挑战需求、找遗漏、查错误、检查可测性、评审设计是否走偏、检查过度设计，或要求在 Superflow docs/design/implementation 前做独立审查。
+---
+
+# Superflow Requirement Review
+
+对当前 OpenSpec change 进行独立、对抗式但基于证据的反向评审。评审不是旁路建议：
+阻塞级问题必须回写并修正文档，复审通过后才能离开 docs 阶段。
+
+## 边界
+
+- 在复杂需求完成逐功能澄清、形成可评审文档草案后使用。
+- 不替代 `superflow-clarify` 的 owner 决策确认，也不替代源码、Mapper/SQL、DB 和
+  真实调用方核查。
+- 不创建平行需求体系；产物必须落在当前 `openspec/changes/<change>/`。
+- 不只输出意见清单。发现成立的问题后，必须修正 canonical 文档并复审。
+- 不为了“解决遗漏”增加没有真实需求或复用证据的表、接口、服务、缓存和状态。
+
+## 必须读取
+
+按当前任务范围读取：
+
+- 原始需求索引：`source-ingestion.md`、`feature-inventory.md`、`feature-gates.md`
+- 合同：`proposal.md`、`api.md`、`specs/**/spec.md`、`design.md`
+- 证据：`source-code-audit.md`、`database-contract.md`、`release-sql.md`
+- 交付：`tasks.md`、`tests.md`、`traceability-matrix.md`、
+  `review-checklist.md`、`sdd-quality-gate.md`、`test-report.md`
+- 当前源码、Mapper/XML、真实前端/小程序/H5 调用方、sibling repo，以及必要的
+  只读数据库证据
+
+缺少某类文件时记录为评审发现，不得凭聊天记忆补结论。
+
+## 评审流程
+
+### 1. 冻结评审基线
+
+记录 change、当前 phase、需求来源、功能范围、handoff hash 和已确认/待确认决策。
+一次只评审一个已冻结功能；不得把下一功能的问题混入当前结论。
+
+### 2. 建立证据资格
+
+先完成平台影响面发现，再回到源码、Mapper/SQL、真实调用方和必要的只读 DB。
+understand-anything 只作定位。将证据标记为 `current`、`legacy`、`unmounted`、
+`data-model-only`、`owner-confirmed` 或 `blocked`。
+
+仓库和数据库能查明的事实不得转问用户。只有 owner 取舍才进入澄清，并且一次只问
+一个决策问题。
+
+所有未决项先按解决责任分类，禁止统一写成“外部待确认”：
+
+- `SOURCE_INVESTIGATION`：源码、依赖、配置、日志或只读数据库可以查明。评审者必须
+  继续调查，未查完不得退出评审，也不得转问用户。
+- `OWNER_DECISION`：存在两个以上成立方案，需要产品或业务 owner 取舍。返回
+  `superflow-clarify`，一次只问一个问题。
+- `EXTERNAL_CONTRACT`：第三方请求/响应、签名、幂等、枚举、回调或跨服务责任合同。
+  只要会改变 API、SQL、状态机、安全实现或测试断言，就属于实现阻塞项，必须取得
+  合同证据后才能 PASS；“已在文档标记 Blocked”不算关闭。
+- `EXECUTION_EVIDENCE`：已经冻结实现合同，仅等待部署、真实调用、迁移或运行证据。
+  可以留在 tests/test-report 阻塞交付，但不得伪装成合同未知项。
+
+### 3. 六向反查
+
+逐项从结果反推前提，不能只沿设计正向复述：
+
+1. **业务闭环**：输入、触发、前置条件、处理、输出、异常、恢复、取消/重复动作。
+2. **源码事实**：真实入口、全部写入方、读取/过滤方、遗留能力、跨仓消费者、DB样本。
+3. **合同一致性**：PRD/截图、UI、API、DTO/VO、DB、状态枚举、SQL、tests 和 tasks。
+4. **失败与边界**：越权、并发、幂等、超时、不确定结果、乱序回调、部分失败、脏数据。
+5. **复杂度减法**：重复字段、平行接口、无必要 Service、缓存/MQ/定时任务、推测性兼容。
+6. **可交付性**：每条需求是否有实现任务、RED/GREEN、真实入口、DB/log证据和验收口径。
+
+涉及数据库时必须使用 `superflow-table-impact-analysis`，或在不可用时按同等规则降级
+执行并记录原因。
+
+### 4. 记录发现
+
+创建或更新当前 change 的 `requirement-review.md`：
+
+```markdown
+---
+change: <change-name>
+review_verdict: BLOCKED
+implementation_readiness: BLOCKED
+open_blockers: <number>
+open_external_contracts: <number>
+open_source_investigations: <number>
+open_owner_decisions: <number>
+---
+
+# 需求反向评审
+
+## 评审基线
+- change：
+- phase：
+- 功能范围：
+- 来源与证据：
+- handoff hash：
+
+## 闭环矩阵
+| 功能点 | 输入/触发 | 处理 | 输出 | 异常 | 恢复/重复 | 证据 | 结论 |
+|---|---|---|---|---|---|---|---|
+
+## 评审发现
+| ID | 等级 | 维度 | 位置 | 问题 | 证据 | 影响 | 最小修正 | 状态 |
+|---|---|---|---|---|---|---|---|---|
+
+## 未关闭阻塞项
+| ID | 分类 | 影响的实现合同 | 解决责任 | 下一证据/问题 | 状态 |
+|---|---|---|---|---|---|
+
+## 过度设计与欠设计
+| 设计项 | 现有复用 | 必要性 | 删除/保留结论 | 证据 |
+|---|---|---|---|---|
+
+## 复审结论
+- BLOCKED / PASS
+- 未关闭发现：
+- 已修正文档：
+- 仍需 owner 决策：
+```
+
+等级只能使用：
+
+- `BLOCKER`：需求事实、API/DB/状态、安全、真实入口或验收合同错误，阻塞推进。
+- `IMPORTANT`：高概率造成遗漏、返工或不可测，必须在 docs 阶段修正。
+- `SUGGESTION`：不影响合同正确性的改进建议，可由 owner 决定。
+
+### 5. 整改
+
+每个成立的 `BLOCKER/IMPORTANT` 必须：
+
+1. 修正原始 canonical 文档，而不是只修改 `requirement-review.md`。
+2. 同步 API、design、spec、SQL、tasks、tests、traceability 和 quality gate 中受影响项。
+3. 记录“问题 → 修正文件 → 测试/证据”的闭环。
+4. 若修正改变 owner 已确认合同，停止并回到 `superflow-clarify`。
+
+### 6. 独立复审
+
+整改后重新从需求来源和源码证据检查，不以“文档已经修改”为通过依据。
+
+通过条件：
+
+- 所有 `BLOCKER/IMPORTANT` 已关闭并有文件与测试证据。
+- 没有未解释的 UI/API/DB/SQL/status/tests 漂移。
+- 复杂度减法结论成立，没有无证据的新抽象。
+- `SOURCE_INVESTIGATION` 已穷尽并回写证据，数量为0。
+- owner 决策均已记录，`OWNER_DECISION` 数量为0。
+- 会改变实现的 `EXTERNAL_CONTRACT` 已取得证据并冻结，数量为0；仅写成
+  `Blocked`、分配 owner 或列入任务不算关闭。
+- 剩余项只能是不会改变实现合同的 `EXECUTION_EVIDENCE`，并已进入测试/发布门禁。
+- `requirement-review.md` 结论为 `PASS`。
+- front matter 精确记录 `review_verdict: PASS`、`implementation_readiness: READY`、
+  `open_blockers: 0`、`open_external_contracts: 0`、
+  `open_source_investigations: 0` 和 `open_owner_decisions: 0`。
+
+### 7. 刷新门禁
+
+文档修正后刷新 handoff，并运行 docs guard 与 OpenSpec strict validate。将
+`requirement-review.md` 路径、复审结论和未关闭项同步到 `sdd-quality-gate.md` 与
+`test-report.md`。
+
+## 禁止项
+
+- 禁止只按文档文字评审而不核源码和真实入口。
+- 禁止把数据模型可表达能力当成当前产品行为。
+- 禁止用“字段非空、接口200、编译通过”替代业务语义正确。
+- 禁止为了覆盖边界而虚构默认值、fallback、状态或兼容层。
+- 禁止把评审结果落到其他流程目录，导致 OpenSpec change 无法追踪。
+- 禁止未关闭阻塞问题却将 docs/design 标为通过。
+- 禁止以“文档已记录”“已有 owner”“待联调”关闭会改变实现的外部合同。
+- 禁止 `review_verdict: PASS` 与 `implementation_readiness: BLOCKED` 并存。
+
+## Handoff
+
+评审通过后继续当前 Superflow 阶段；若发现 owner 决策缺失，返回
+`superflow-clarify`；若发现文档合同缺失，返回 `superflow-docs` 并在修正后再次执行
+本 skill。

package/assets/skills/superflow-requirement-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Superflow 需求反向评审"
+  short_description: "基于源码反查需求与设计缺口并推动整改复审闭环"
+  default_prompt: "使用 $superflow-requirement-review 对当前 OpenSpec 需求和设计执行反向评审并闭环整改。"

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

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

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

@@ -23,6 +23,21 @@ any full SDD document or implementation prompt is generated.
 - Do not freeze a feature from product text or understand-anything output alone
   when code impact is relevant. Current source, Mapper/XML, database samples,
   API contracts, or real consumer entry points must confirm the design.
+- For features that depend on existing behavior, table relationships, or call
+  chains, create a `source-code-audit.md` Source Fact Freeze Card before
+  freezing: `Business conclusion | understand-anything locator | Data model |
+  All writers | Real user entry | Current callers | Legacy conflict | DB check
+  required | Conclusion level | owner decision`. Treat understand-anything only
+  as a locator and confirm every conclusion in source, Mapper/SQL, current
+  callers, or read-only DB evidence.
+- Classify evidence as `current`, `legacy`, `unmounted`, `data-model-only`,
+  `owner-confirmed`, or `blocked`. If `List`, `orderIds`, `batchInsert`, or a
+  one-to-many relation exists while the real UI/mini-program/H5 submits one
+  item, add a Conflict Audit and do not infer current batch behavior.
+- Before asking the user, record a Question Eligibility Gate covering source,
+  Mapper/SQL, frontend/mini-program/H5 callers, sibling repositories, and the
+  DB check or skip reason. Do not ask the user for facts discoverable from the
+  repository or read-only data; ask only for owner-intent decisions.
 - When the feature depends on existing code relationships, field ownership,
   table joins, data permissions, status transitions, or upstream/downstream
   calls, verify the relationship before freezing with current evidence:
@@ -81,6 +96,8 @@ Create or update these files in the active OpenSpec change directory:
 - `ui-contract.md`: page fields, controls, buttons, list columns, dropdowns, API/DTO/DB mapping.
 - `gap-analysis.md`: UI/document/source gaps and over-design risks.
 - `spec-freeze-review.md`: freeze card for the current feature.
+- `source-code-audit.md`: source fact freeze card, evidence classifications,
+  conflict audit, and question eligibility gate.
 - Platform impact evidence in one of the above documents: discovery method,
   understand-anything index status when available, analyzed platform scope,
   impacted modules/interfaces/tables, regression risks, source/DB/API

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

@@ -21,6 +21,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 
 ## Preconditions
 
+- When the change modifies a database schema, index, constraint, seed data, or
+  historical data, `release-sql.md` must already contain the complete executable
+  release SQL, an exact target `.sql` path, `copy_policy: verbatim`, and a valid
+  `sql_sha256`. Source-level HOW design must not defer SQL design to an
+  implementation prompt.
+
 - `proposal.md`, `api.md`, `design.md`, `tasks.md`, `tests.md`,
   `traceability-matrix.md`, `sdd-quality-gate.md`, and `test-report.md` exist.
 - `.sdd/state.yaml` exists and is in `phase: design`. If still `docs`, run:
@@ -38,15 +44,31 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 
 1. Read `.sdd/handoff/sdd-context.md` plus original `api.md`, `design.md`,
    `tasks.md`, and `tests.md`.
-2. If design discussion is still evolving, maintain
+2. For a database change, verify `release-sql.md` before source-level HOW
+   design: one complete executable SQL block, exact destination, normalized
+   SHA-256, pre/post checks, and explicit verbatim-copy references in
+   `design.md`, `tasks.md`, and `sdd-quality-gate.md`. Any unresolved type,
+   default, index, migration rule, or target path returns to
+   `$superflow-docs`; it must not be deferred to `$superflow-implement`.
+3. If design discussion is still evolving, maintain
    `.sdd/handoff/brainstorm-summary.md` with confirmed, candidate, pending, and
    rejected items. Do not create final technical design from memory only.
-3. Use Superpowers `brainstorming` or equivalent deep design reasoning to
+4. Use Superpowers `brainstorming` or equivalent deep design reasoning to
    decide source-level HOW.
-4. Write:
+5. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-5. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
+6. Complete `Minimal Design Review` before expanding source-level HOW. For
+   every new table, field, API, service/component, abstraction, cache,
+   async/MQ/event flow, scheduled job, or compatibility layer, prove existing
+   reuse options, necessity, and why the simplest direct implementation is
+   insufficient. Prefer one owner, one write path, one transaction, and
+   set-based operations when they satisfy the contract. Remove speculative
+   extension points, duplicate DTO/API layers, derivable persistence,
+   premature caches, and async compensation without measured need. Record
+   retained and removed counts; unresolved simpler alternatives keep the
+   design blocked.
+7. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
    callback, third-party, mini-program, gateway, or adapter changes, include
    `Architecture Boundary And Call Direction`. Prove owner module, call
    direction, existing entry/exit points, proposed entry/exit points, evidence
@@ -54,7 +76,7 @@ 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 third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+8. 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,
@@ -66,7 +88,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    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,
+9. 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
@@ -76,10 +98,17 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    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
+   When the selected design is version-based optimistic locking, record the
+   exact database atomic compare-and-set statement and affected-row decision:
+   the update predicate contains both the stable row identity and expected
+   version; a zero-row result distinguishes missing data from version conflict.
+   The TDD plan references the `tests.md` concurrent stale-version case proving
+   one winner, one conflict, and one increment. Do not defer this decision to
+   the managed Executor prompt.
+10. 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.
-9. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+11. 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,
@@ -98,12 +127,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.
-10. Record state:
+12. 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
    ```
-11. Update `design.md` with `Superpowers Technical Design Handoff`, update
+13. 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
@@ -111,7 +140,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.
-12. Run:
+14. 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

@@ -64,12 +64,29 @@ For complex requirements, verify these before writing docs:
   checks when source is insufficient. Graph output or chat explanation alone is
   not sufficient. If this evidence is missing and the relationship affects
   design, stop and return to `$superflow-clarify`.
+- For full-workflow existing-system changes, `source-code-audit.md` must contain
+  the source fact freeze card, current/legacy/unmounted/data-model-only/
+  owner-confirmed/blocked classifications, all writers and real callers, DB
+  evidence or a skip reason, and the owner decision boundary. `List`,
+  `orderIds`, `batchInsert`, or one-to-many schema signals that conflict with a
+  single-item real entry require an explicit conflict audit. Missing evidence
+  blocks docs even when understand-anything contains a plausible summary.
 - For any database-backed design, the docs include table-to-code reverse impact
   evidence: every affected table/field, all writers/readers/filters, sibling
   repo or third-party consumers, real user-facing endpoints, reverse-state
   scenarios, and validation cases. If the docs only describe the write/sync
   path and do not prove consumers, stop and return to `$superflow-clarify`. Use
   `$superflow-table-impact-analysis` when available.
+- For any schema, index, constraint, seed-data, or historical-data change,
+  docs MUST create `release-sql.md` before `$superflow-design` or implementation
+  prompts. It contains exactly one complete executable `sql` block and front
+  matter with `database_change: true`, an exact `target_sql_path`,
+  `copy_policy: verbatim`, and the normalized payload `sql_sha256`. Freeze all
+  prechecks, DDL/DML, post-verification, defaults, constraints, indexes, and
+  migration semantics here. `design.md`, `tasks.md`, and
+  `sdd-quality-gate.md` must reference it and prohibit implementation agents
+  from editing the SQL. Placeholder paths, missing hashes, SQL fragments, or
+  deferred SQL design block docs completion.
 - For any status, enum, sync, derived, default, or compatibility behavior, the
   docs include business semantic evidence:
   `Source field | Source enum | Target field | Target enum | Consumer meaning | Business basis | Unknowns`.
@@ -103,6 +120,52 @@ For complex requirements, verify these before writing docs:
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
   any gate is missing from `design.md`, `tests.md`, or quality gate, stop and
   complete the docs first.
+- Low-freedom means the Executor has no unresolved implementation or test-design
+  choice. `design.md` names reusable modules, exact change points, call/data flow,
+  transaction and concurrency boundaries, error behavior, and implementation
+  order. `tests.md` names environment, fixtures, startup command, steps,
+  automation command, response/DB/log assertions, cleanup, and evidence paths.
+  If two materially different implementations or acceptance paths remain valid,
+  return to clarification/design instead of delegating the choice to development.
+- For full workflow changes, `design.md` must include a `Minimal Design Review`
+  before docs freeze. Inventory every proposed table, field, API,
+  service/component, cache, async/MQ/event flow, scheduled job, compatibility
+  layer, and abstraction. Record existing reuse evidence, necessity, the
+  simplest implementation, removed/rejected complexity, and blockers.
+  Prefer extending current modules and synchronous transactions. Do not keep a
+  layer only for hypothetical future flexibility; remove it without evidence.
+- `sdd-quality-gate.md` must record the minimal-design verdict as `PASS` or
+  `BLOCKED`; only `PASS` may leave docs/design. Missing reuse evidence, parallel APIs/models, redundant persisted
+  fields, speculative cache/async/compensation, or an unresolved simpler option
+  blocks docs completion.
+- After a reviewable full-workflow contract draft exists, run
+  `$superflow-requirement-review` before docs guard completion. It must create
+  `requirement-review.md`, repair canonical documents for every confirmed
+  `BLOCKER/IMPORTANT` finding, and re-review from source evidence. Record its
+  verdict and unresolved findings in `sdd-quality-gate.md` and `test-report.md`.
+  Source-resolvable unknowns must be investigated, owner decisions must return to
+  clarification, and implementation-affecting external contracts must be evidenced and frozen.
+  Merely documenting or assigning a blocker does not close it. A missing report, non-READY
+  implementation verdict, or nonzero blocker count prevents transition to design.
+- Before developer handoff, a full workflow records three independent reviews
+  against the current handoff hash in `.sdd/reviews/document-review.json`:
+  `source-contract`, `architecture-minimality`, and `e2e-environment`.
+  Resolve discoverable gaps autonomously and ask owner-only blockers once at the end.
+- Explore the declared local/dev/test configuration before handoff and record
+  fail-safe probes in `.sdd/readiness/environment.json`. Its v2
+  `executionContract` uniquely freezes the application location, dependency
+  policy, config sources, and allowed/forbidden overrides. Tests use verified
+  startup commands, ports, simulators, and dependencies; reachability alone is
+  not an environment contract and discovery is not deferred to the developer.
+- Cross-repo, cross-service, device, MQ, callback, state-machine, or three-plus
+  module logic includes Mermaid `sequenceDiagram` and `flowchart`/`stateDiagram`.
+- Run `superflow check <change> --level coding-ready` after prompts are complete.
+  A failed implement gate is fixed by the docs workflow, never delegated to the
+  developer Agent.
+- When an upstream caller receives an explicit failure and owns refund/cancel
+  compensation, default to fail-fast, fail-closed, at-most-once, and
+  caller-owned compensation. Transparent retry/reroute/resend requires owner
+  approval in the cross-system failure ownership boundary.
 - `design.md` stays the OpenSpec/SDD design contract: requirement mapping,
   API/DB/field semantics, source facts, real-entry call chain, no-fallback
   boundary, risks, and acceptance hooks. It must not try to own all source-level
@@ -163,12 +226,20 @@ applicable:
 - `specs/<capability>/spec.md`
 - `design.md`
 - `tasks.md`
+- Every `tasks.md` checkbox must carry exactly one machine category:
+  `[local_required]`, `[environment_required]`, or `[release_required]`.
+  Locally executable code, tests, startup, and browser checks are local_required;
+  free-form Blocker/owner prose cannot replace the category.
 - `tests.md`
 - `test-report.md` skeleton
 - `sdd-quality-gate.md`
 - `traceability-matrix.md` when tasks are split
 - `mock.md` when external dependencies exist
 - `review-checklist.md` when implementation will be split
+- `requirement-review.md` for full-workflow changes before docs completion
+- `source-code-audit.md` for full existing-system, DB, cross-repo, or real-entry changes
+- `release-sql.md` for every database change; omit it only when the docs prove
+  that no schema/data migration is required
 - `.sdd/state.yaml`
 - `.sdd/handoff/sdd-context.md`
 - `.sdd/handoff/sdd-context.json`
@@ -251,6 +322,11 @@ Use references only as needed:
   the relationship judgment as `confirmed/partially confirmed/unknown` when a bug fix hinges on
   existing data or call-chain behavior.
 - `design.md` must reference the frozen `api.md` fields and errors.
+- `design.md` must include `Minimal Design Review` with:
+  `Design item | Existing capability/reuse evidence | Necessary? | Simplest implementation | Removed/rejected complexity | Evidence/blocker`.
+  Count new tables, fields, APIs, services/components, caches, async flows,
+  jobs, and compatibility layers. A zero count is valid and preferred when
+  existing capabilities close the contract.
 - `design.md` must include a "Field Semantic Contract" table for every risky field:
   `Field | Source table/DTO/event | Real semantics | Target field | Target semantics | Equivalent? |
   Evidence anchor | Forbidden usage | Unknowns/owner`.
@@ -282,6 +358,25 @@ Use references only as needed:
   `Case ID | Requirement/scenario | Level L1/L2/L3/L4 | Precondition data | Steps |
   Automation command | Response assertion | DB assertion | Log assertion | RED expected failure | GREEN expected pass |
   test-report evidence location`.
+- For L3/L4 input validation, protocol rejection, and exceptional branches,
+  `tests.md` also freezes the real injected payload and evidence that it reaches
+  the intended parser or validation branch; matching the same HTTP status alone
+  is not coverage. Raw malformed JSON, wrong Content-Type, unauthorized identity,
+  and invalid fields must be sent on the real wire protocol and assert no side effect.
+- When a task adds or copies an owner/cleanup primitive for local processes,
+  containers, or temporary resources, `design.md`, `tests.md`, and
+  `test-report.md` freeze resource identity fields, producer/consumer equality
+  relations, and refusal-to-clean tests for every mismatch (for example nonce,
+  PID, port, and process signature). When reusing an unchanged certified owner
+  helper, record only its integrity, task parameters, one failure cleanup, and
+  final zero residue; do not repeat framework certification.
+- When a design uses a version field for optimistic locking, `design.md` freezes
+  the database-level atomic compare-and-set boundary, conflict response, and
+  zero-row distinction between missing data and stale version. A read-then-write
+  check alone is blocked. `tests.md` includes two concurrent requests holding
+  the same old version and asserts exactly one success, one conflict, and one
+  version increment. The implementation prompt only inherits these frozen case
+  IDs and commands; managed orchestration never invents the business design.
 - Each visible UI field, button action, list column, dropdown, and enum must map to API/DTO/DB/tests or be explicitly out of scope.
 - Every spec scenario must have at least one test case.
 - Every implementation batch must have at least one test that can fail before
@@ -315,6 +410,26 @@ Use references only as needed:
   `RED failure evidence`, `GREEN pass evidence`, `interface automation evidence`, `DB evidence`,
   `log evidence`, `manual/blocking cases`, and `Partially verified boundary`.
   Each section must reference concrete `tests.md` case IDs.
+- `tests.md` freezes runtime-specific acceptance instead of leaving it to
+  managed orchestration:
+  - Spring Boot/backend services: verified startup command, dynamic or planned
+    isolated port, readiness condition, at least one real HTTP invocation, and
+    failure evidence when the environment blocks startup.
+  - `.vue/.tsx/.jsx`, frontend API registration, page permission, or visible UI
+    behavior: frontend startup plus real-browser Playwright/Cypress cases and
+    page assertions; build, static inspection, and mocks are supplementary only.
+  - Controller/API DTO plus frontend request changes: backend Controller contract,
+    frontend request contract, and dynamic API export/call-resolution snapshot
+    when applicable.
+  - Named runtime backends such as MySQL, Testcontainers, a real browser, or a
+    real service: exact backend and command; H2, mocks, stubs, in-memory stores,
+    and compatibility modes never close the named gate.
+  - Multi-repository/service changes: build/runtime checks for every affected
+    repository plus the real cross-repository path; one repository's evidence
+    never substitutes for another.
+  `design.md` records why each runtime and repository is in scope; `tasks.md`
+  classifies local, environment, and release work; the implementation prompt
+  inherits the exact case IDs, commands, assertions, and evidence paths.
 - 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