@chenmk/superflow 0.4.0 → 0.5.0

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,13 @@ 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
@@ -114,6 +138,34 @@ For complex requirements, verify these before writing docs:
   `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
@@ -174,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`
@@ -298,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
@@ -331,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

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

@@ -5,6 +5,13 @@ description: Use when a user asks for the SuperBridge Flow, SDD, OpenSpec, requi
 
 # SuperBridge Flow Pipeline
 
+When maintaining Superflow CLI itself, first read repository-root
+`docs/superflow-cli-design-principles.en.md` and
+`docs/superflow-cli-evaluation-framework.en.md`; managed-work changes also read
+the managed constitution and protocol. Identify the owner layer before editing,
+then record baseline, hypothesis, scenario, result, and rollback condition under
+the unified evaluation framework.
+
 ## Role
 
 This is the main router and stateful workflow orchestrator for SuperBridge Flow.
@@ -21,35 +28,93 @@ other:
 
 ## Managed Work And Dual-Agent Closure
 
+When the Superflow MCP is installed for the host Agent, prefer
+`superflow_managed_start/status/wait/message/submit_review` instead of manually
+spawning `superflow pipeline` from chat. MCP tasks are always `external_host`:
+the current host keeps the user conversation and reviews directly, while the
+background service starts only the peer executor. Never spawn a nested
+supervisor CLI. Wait with `superflow_managed_wait` locally instead of spending
+model turns on periodic status checks. Use the CLI equivalent below only when
+MCP is unavailable.
+Call `superflow_managed_runtime` before task creation. If its fingerprint is
+stale, require a Host restart and never start a new validation task through the
+pre-install MCP process.
+
 When the user says to use Superflow for managed delivery and provides an
 implementation prompt, change directory, or direct task, use built-in managed
 mode. Do not require the user to name `superflow-pipeline`, roles, or CLI flags:
 
+Before start, perform one Host semantic routing step. Docs-only requests stop
+after autonomous document review and Coding Ready without a managed Task. A
+user-approved change/prompt is frozen from its original path. Only a bounded
+verbal request enters minimal or standard directly. Direction-changing API,
+data, concurrency, cross-repository, or owner choices return to
+clarification/documents; Runner regexes and Executor improvisation do not decide them.
+
 ```bash
 superflow pipeline "<implementation prompt, change directory, or direct task>" --managed --project "<project root>" \
-  --supervisor codex --executor claude --language en
+  --supervisor current --executor peer --language en
 ```
 
-Swap the roles when Claude is the current entry agent. The command always uses
-the independent background service while following the local task journal to a
-terminal state, then the current agent reads the report and summarizes in the
-same conversation. Losing the follower does not stop the task. Read
-`references/managed-work.md` before dispatch. Do not spawn the peer CLI by hand.
+`current/peer` resolves the host automatically: a Codex host drives Claude and a
+Claude host drives Codex. Ambiguous environments fail closed and require explicit
+roles. The background service
+invokes only the executor; the current host agent performs the read-only review
+without spawning another copy of itself. After executor delivery, read
+`host-review-N.md`, write the structured review JSON, then resume with
+`--resume-task <task-id> --submit-host-review <json>`. Losing the follower does
+not stop the task. Read `references/managed-work.md` before dispatch.
+
+Managed delivery uses the lower-cost executor for implementation and validation;
+the more expensive host only freezes the goal, supervises, and reviews delivery
+quality. The host must not code, build, start, test, or manage executor processes.
+When the task reaches `external_supervisor_review_required`, review, submit, and
+resume automatically in the same turn; it must not stop and wait for manual user handoff.
+Only an owner decision, unavailable external authority, or final Git approval may
+interrupt the user.
 
 Hard gates:
 
-- Persist one supervisor session and one executor session per task; resume exact IDs.
+- Use a fresh short session for every execution and repair call. Hand off through
+  the current workspace, frozen prompt, persisted result, and findings; keep old
+  session IDs only for audit and never resume a long session indefinitely.
+- The first invocation must receive the frozen task prompt automatically. Every
+  later invocation must first receive and read a condensed handoff containing at
+  least the prompt path/hash, task progress, local pending work, external
+  prerequisites, all current findings, diff stat, and recent report. Old and new
+  sessions both treat the handoff and current workspace as authoritative.
+- In `external_host` mode the current agent reviews; the service must not spawn a
+  nested Codex or Claude CLI for the supervisor role.
+- Host conversation and review do not count as background Agent invocations;
+  only real executor calls consume the execution budget.
 - Task contract, event journal, review results, and evidence are authoritative.
 - Maximum 5 reviews, 7 executor calls, and 12 total agent calls.
 - Revalidate the frozen contract and hard limits on every start or resume. Engineering work cannot enter review with only one verification category.
 - Resolve a change directory through `.sdd/state.yaml` `implementation_prompt`, reject `tasks.md` as an execution entry, and freeze one prompt snapshot plus SHA-256 for both agents.
 - Supervisor is read-only; executor cannot edit `.superflow/tasks` or commit/push/publish.
-- A passing run stops at `awaiting_git_approval`; Git requires the user's approval.
-- Use `superflow status <project-root>` instead of model polling.
+- Frozen requirements, designs, prompts, handoffs, rules, and task facts are
+  immutable protected inputs. Tasks and test reports are retained progress
+  evidence that may be updated but not deleted. Executor cleans runtime and
+  workspace-temporary resources and keeps delivery artifacts and protected
+  contracts for Host review.
+- Never use pkill, killall, a bare kill, port/name-only cleanup, or rm -rf
+  without owner-helper verification. Native hooks block before mutation and
+  preflight/final gates verify every Host.
+- A passing run enters `environment_validation_blocked`, `local_delivery_ready`, or `release_ready`; Git always requires user approval.
+- Default MCP waits to a 240-second Host-compatible transport window. On window
+  expiry, immediately continue only from returned `latestSequence`; do not call
+  status, read full events, or restart Executor. Hosts with longer tool limits may
+  explicitly request up to twelve hours; semantic supervision runs only for attention.
+- When the user names a task-prompt document, pass its original path to start and verify the frozen SHA-256; never replace it with a host summary.
+- Page/permission changes require frontend startup and real-browser E2E; cross-stack API changes require both backend and frontend contract tests.
 - `superflow-managed-work-check.mjs` must pass before delivery-ready status.
 - Record the single delivery-ready event only after the integrity script passes.
 - After the managed command returns a terminal state, read the task report and summarize it to the user instead of returning only a task ID.
 - Freeze the selected language into the task contract. Executor and reviewer prompts, resumed rounds, journals, reports, notifications, and errors must inherit that language without switching mid-run.
+- Claude Executor long sessions use early auto-compaction by default, while
+  explicit user environment values win. Reload the frozen prompt and handoff after
+  compaction. Final `result.usage` is authoritative; a large value alone does not
+  prove Runner double counting.
 
 ## Phase Order
 
@@ -59,6 +124,10 @@ hotfix:
 1. clarify: ingest requirements one feature at a time, freeze scope, and produce
    source-ingestion, feature gates, inventory, UI/API gaps, and freeze review.
 2. docs: generate OpenSpec/SDD contract artifacts and the first handoff package.
+   Before closing docs, run source-backed requirement review, repair blocking
+   findings, resolve all source investigations, owner decisions, and implementation-affecting
+   external contracts, then record `requirement-review.md`. Naming or assigning a blocker does
+   not close it.
 3. design: let Superpowers produce source-level technical design from the frozen
    contract and codebase evidence.
 4. implement: generate implementation prompts, execution plans, worktree/port
@@ -75,6 +144,8 @@ hotfix:
   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.
+- Requirement review, reverse review, omission search, design challenge,
+  testability review, or over-design review: use superflow-requirement-review.
 - Confirmed requirement needing full docs: use openspec-propose, then
   superflow-docs.
 - Contract docs exist and code-level HOW is needed: use superflow-design.
@@ -111,6 +182,23 @@ When the router selects embedded deep clarification, follow these rules inside
 
 ## Required Artifacts
 
+### Source Fact Freeze And Question Eligibility (Blocking)
+
+- When a full workflow involves existing behavior, DB/table relationships,
+  cross-repository impact, or a real entry, docs must include
+  `source-code-audit.md` with: `Business conclusion | understand-anything
+locator | Data model | All writers | Real user entry | Current callers |
+Legacy conflict | DB check required | Conclusion level | owner decision`.
+- understand-anything is a locator, not the final source of truth. Classify
+  evidence as `current`, `legacy`, `unmounted`, `data-model-only`,
+  `owner-confirmed`, or `blocked`.
+- If `List`, `orderIds`, `batchInsert`, or a one-to-many model conflicts with a
+  single-item real entry, complete a Conflict Audit instead of inferring current
+  product behavior from the data structure.
+- Before asking the user, search source, Mapper/SQL, frontend/mini-program/H5
+  callers, sibling repositories, and read-only DB data when needed. Do not turn
+  repository-verifiable facts into clarification questions.
+
 ### Canonical OpenSpec Change Directory (Blocking)
 
 - Superflow must use the OpenSpec CLI single-level layout:
@@ -139,6 +227,7 @@ For a full change, the docs phase must create or refresh:
 - review-checklist.md
 - sdd-quality-gate.md
 - test-report.md
+- source-code-audit.md when the source fact gate is triggered
 - .sdd/state.yaml
 - .sdd/handoff/sdd-context.md
 - .sdd/handoff/sdd-context.json
@@ -172,6 +261,58 @@ Rules:
 
 ## Decision Points
 
+## Autonomous Document Delivery Closure
+
+A full-workflow docs Agent must not equate a successful keyword/file guard with
+100% implementation readiness. Before developer handoff, record at least three
+independent review lenses against the same current handoff hash in
+`.sdd/reviews/document-review.json`:
+
+1. `source-contract`: source, cross-repo callers, contracts, and real entries;
+2. `architecture-minimality`: ownership, reuse, simplest design, failure owner,
+   and overdesign;
+3. `e2e-environment`: startup order, configured environment, simulators,
+   automation, DB/log assertions, and cleanup.
+
+The Agent resolves every source/config/log/probe-discoverable gap itself. Only
+business-owner decisions, unavailable credentials/authority, or external
+resources may remain in `openOwnerDecisions`, and they are asked as one final
+batch. Open findings mean `BLOCKED_FOR_OWNER_BATCH`, never 100%.
+
+Explore the configured environment during docs and record
+`.sdd/readiness/environment.json`. Only fail-safe `file`, `directory`,
+`executable`, `tcp`, and `http` probes are allowed. Never print credentials or
+write production data. Respect the declared local/dev/test scope instead of
+requiring a remote environment by default. Use
+`superflow.environment-readiness.v2` to freeze the application location,
+`local-isolated/shared-dev/shared-test/mixed` dependency policy, config sources,
+allowed/forbidden overrides, and a `contractRef` for every probe. Reachability
+alone is not an environment execution contract.
+
+Cross-service, cross-repo, device, MQ, callback, scheduler, state-machine,
+compensation, or three-plus-module logic declares `complex_logic: true` or
+`mermaid: required` in `.openspec.yaml` and includes both a Mermaid
+`sequenceDiagram` and a `flowchart`/`stateDiagram` showing failure exits,
+compensation owner, and forbidden fallback.
+
+Run `superflow check <change> --level coding-ready` after all prompts are ready.
+It validates YAML, OpenSpec, docs/design/implement, every prompt and exact link,
+review receipts, environment probes, and Mermaid diagrams, then writes a receipt
+bound to the current handoff hash. Never delegate a failed implement gate to the
+developer Agent.
+
+## Cross-System Failure Ownership And Compensation Boundary
+
+Record `Failure signal | Interpreter | Compensation owner | Retry allowed? |
+Idempotency basis | Accepted race window | Extreme fallback | Owner approval`.
+When the caller receives an explicit failure and owns refund/cancel/state
+compensation, the downstream adapter defaults to `Fail-fast + Fail-closed +
+At-most-once + Caller-owned compensation`: no transparent retry, reroute,
+resend, or guessed success. Accept a bounded false-negative window when duplicate
+side effects are more harmful. Additional fallback requires explicit owner
+approval and a proven idempotency basis, collected with other owner-only
+questions in one final batch.
+
 Record irreversible or ambiguous decisions in references/decision-point.md
 format. Do not store decisions only in chat memory.
 
@@ -187,6 +328,9 @@ Decision points include:
 
 ## Quality Gates
 
+The machine-readable review, environment, Mermaid, and Coding Ready contracts
+are defined in `references/document-readiness.md`.
+
 The workflow must preserve these gates:
 
 - API-first contract freeze before implementation.
@@ -208,6 +352,13 @@ The workflow must preserve these gates:
 - Architecture boundary and call-direction analysis for multi-repo, service,
   SDK, MQ, scheduler, callback, gateway, adapter, device, or third-party flows.
 - SQL risk review before implementation for DB changes.
+- Frozen release SQL before source design for DB changes. `release-sql.md` must
+  declare `database_change: true`, an exact placeholder-free
+  `target_sql_path`, `copy_policy: verbatim`, and the normalized SQL payload
+  `sql_sha256`, with exactly one complete executable SQL block containing the
+  required prechecks, DDL/DML, migration, and post-verification. Implementation
+  agents may only copy the block verbatim and verify the hash; any SQL design
+  omission returns to docs and requires a refreshed handoff.
 - Real-entry acceptance for integration, device, callback, payment, client, or
   cross-system flows. Mock-only is never real integration.
 - Delivery completeness: runtime code changes must update the relevant task
@@ -226,6 +377,9 @@ Implementation prompts must require:
 - worktree and port plan for parallel work;
 - real-entry validation commands from tests.md;
 - DB SELECT or SHOW CREATE checks when persisted state is touched;
+- `release-sql.md`, its exact target path, verbatim-copy rule, and SHA-256 when
+  the change touches schema or data migration; prompts must never ask an
+  implementation agent to author or append SQL;
 - log checks and error checks;
 - superflow-verify-integration and superflow-delivery-check before completion;
 - a report format that distinguishes Passed, Partially verified, and Blocked.

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

@@ -21,6 +21,10 @@ review-checklist.md, sdd-quality-gate.md, test-report.md, and technical design.
 
 - Follow OpenSpec/SDD for WHAT and contract.
 - Follow Superpowers technical design for source-level HOW.
+- For database changes, read `release-sql.md`, copy its single SQL block
+  verbatim to the exact `target_sql_path`, and verify `sql_sha256`. Never
+  author, append, reorder, split, or optimize SQL during implementation. Return
+  omissions to docs and refresh the handoff.
 - 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.

package/assets/skills-en/superflow-pipeline/references/document-readiness.md

@@ -0,0 +1,125 @@
+# Document Delivery Readiness Contract
+
+## Applicability
+
+Declare applicability in `.openspec.yaml`. Keyword scans may suggest a risk but
+must not override an explicit, source-backed decision.
+
+```yaml
+schema: superflow/v1
+applicability:
+  cross_repo: true
+  complex_logic: true
+  mermaid: required
+  environment: required
+  database: false
+  external_config: false
+  concurrency: false
+  money: false
+```
+
+`money: false` means this change does not alter money calculation, rounding,
+allocation, or financial display. It is not a bypass when source impact proves
+that money behavior changes.
+
+## Three-Review Receipt
+
+Path: `.sdd/reviews/document-review.json`
+
+```json
+{
+  "schemaVersion": "superflow.document-review.v1",
+  "handoffHash": "<current 64-character handoff hash>",
+  "verdict": "PASS",
+  "openOwnerDecisions": [],
+  "rounds": [
+    { "round": 1, "lens": "source-contract", "inputHash": "<same hash>", "findings": [] },
+    { "round": 2, "lens": "architecture-minimality", "inputHash": "<same hash>", "findings": [] },
+    { "round": 3, "lens": "e2e-environment", "inputHash": "<same hash>", "findings": [] }
+  ]
+}
+```
+
+Do not delete findings. After repair, retain them with `"status": "closed"`,
+evidence, and the closure location. Every round is rechecked against the current
+hash; a PASS for an old hash is invalid.
+
+## Environment Preflight
+
+Path: `.sdd/readiness/environment.json`
+
+```json
+{
+  "schemaVersion": "superflow.environment-readiness.v2",
+  "handoffHash": "<current hash>",
+  "scope": "local-dev",
+  "overall": "READY",
+  "ownerHelpRequired": [],
+  "executionContract": {
+    "applicationLocation": "local",
+    "dependencyPolicy": "shared-dev",
+    "allowLocalProvisioning": false,
+    "allowRemoteDevDependencies": true,
+    "allowedOverrides": ["server.port"],
+    "forbiddenOverrides": ["spring.datasource.url"],
+    "services": [
+      {
+        "id": "service-a",
+        "configSource": { "type": "bundled-profile", "ref": "application-prod.yml" },
+        "startupCommandSource": "tests.md#startup"
+      }
+    ],
+    "dependencies": [
+      {
+        "id": "redis",
+        "kind": "redis",
+        "provisioning": "shared-dev",
+        "configSource": { "type": "bundled-profile", "ref": "application-prod.yml#spring.redis" }
+      }
+    ]
+  },
+  "checks": [
+    { "id": "service-config", "type": "file", "target": "../../../service-a/application-prod.yml", "contractRef": "service:service-a", "status": "READY" },
+    { "id": "redis", "type": "tcp", "host": "redis.dev.internal", "port": 6379, "contractRef": "dependency:redis", "status": "READY" }
+  ]
+}
+```
+
+Supported checks are `file`, `directory`, `executable`, `tcp`, and `http`.
+Never embed credentials or tokens in URLs. Production writes and DB/Redis/MQ
+mutations are not preflight operations.
+
+`executionContract` is the single environment source of truth. Freeze the
+application location, dependency policy, local-provisioning and shared-dev
+permissions, allowed/forbidden overrides, and the config source for every
+service and dependency. `configSource.type` is one of `bundled-profile`,
+`external-file`, `environment`, `cli-override`, or `generated-fixture`.
+Do not mix `local-isolated`, `shared-dev`, and `shared-test`; use `mixed` and
+declare each dependency's `provisioning` when mixing is intentional. Every
+service and dependency needs a matching `contractRef` probe. Legacy v1 reports
+prove reachability only and cannot satisfy Coding Ready.
+
+## Complex Diagrams
+
+When `cross_repo` or `complex_logic` is true, include a Mermaid
+`sequenceDiagram` for the real call and a `flowchart` or `stateDiagram` for
+branches, compensation owner, and forbidden fallback.
+
+## Coding Ready
+
+```bash
+superflow check <change> --level docs
+superflow check <change> --level coding-ready
+```
+
+The second command writes `.sdd/readiness/coding-ready.json`. Any SDD document
+or handoff-hash change invalidates the old receipt. A developer Agent may only
+receive a change with a current receipt.
+
+## Cross-System Failure Ownership
+
+Record `Failure signal | Interpreter | Compensation owner | Retry allowed? |
+Idempotency basis | Accepted race window | Extreme fallback | Owner approval`.
+Default to fail-fast, fail-closed, at-most-once, and caller-owned compensation.
+Retry, reroute, resend, or distributed compensation requires explicit owner
+approval and a proven idempotency basis.

package/assets/skills-en/superflow-pipeline/references/document-templates.md

@@ -32,6 +32,16 @@
 - No-fallback decisions
 - Superpowers technical design handoff
 
+## release-sql.md (required for database changes)
+
+- Front matter: `database_change: true`, exact `target_sql_path`,
+  `copy_policy: verbatim`, and normalized payload `sql_sha256`
+- Exactly one complete executable `sql` block with required prechecks,
+  DDL/DML, migration, and post-verification
+- No placeholder path or deferred SQL design
+- Implementation agents only copy the block verbatim and verify the hash;
+  omissions return to docs
+
 ## tests.md
 
 - Case ID

package/assets/skills-en/superflow-pipeline/references/feature-gated-workflow.md

@@ -11,7 +11,14 @@ requests. Process one feature at a time.
 - ui-contract.md: screen field to API/DTO/DB/test mapping.
 - gap-analysis.md: unknowns, contradictions, and owner decisions.
 - spec-freeze-review.md: final frozen scope and excluded items.
+- source-code-audit.md: source fact freeze card, evidence classifications,
+  conflict audit, and question eligibility gate.
 
 ## Gate
 
 Do not generate full OpenSpec docs until the target feature is frozen.
+For existing-system work, understand-anything is locator evidence only. Confirm
+current behavior from source, Mapper/SQL, real callers, and read-only DB data
+when needed. Classify current versus legacy/unmounted/data-model-only paths and
+audit any List/orderIds/batchInsert/one-to-many signal that conflicts with a
+single-item real entry before asking an owner question.

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

@@ -17,6 +17,13 @@ the new hash before continuing.
 OpenSpec/SDD is canonical for requirements, API, DB, SQL, tests, and acceptance.
 Superpowers technical design is canonical for source-level HOW and execution.
 
+For a database change, SQL is already frozen in
+[release-sql.md](../release-sql.md). The implementation agent may only copy its
+single SQL block verbatim to the exact `target_sql_path`, normalize line endings
+to LF with one trailing newline, and verify `sql_sha256`. Do not add, remove,
+reorder, split, or optimize SQL. Any omission returns to docs and requires a
+refreshed handoff; never design SQL inside the implementation prompt.
+
 ## Required Preflight
 
 - Real entry located.