@chenmk/superflow 0.5.21 → 0.5.22

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

@@ -40,6 +40,26 @@ do not mark archived until the user confirms final closeout.
    ~/.codex/skills/superflow-pipeline/scripts/superflow-archive.sh <change-dir> --apply
    ```
 
+## Recovery after archive relocation
+
+If OpenSpec moved the directory but annotation/state closeout failed, preserve
+artifacts and raw errors. Identify the exact `openspec/changes/archive/<archive-name>`
+from this archive's output or actual operation record. Never guess a historical
+same-name directory or repeat archive from the missing old path. Use the helper:
+
+```bash
+~/.codex/skills/superflow-pipeline/scripts/superflow-archive.sh <explicit-archived-dir> --dry-run
+# Check summary, original authorization, and remaining work; do not expand permission
+~/.codex/skills/superflow-pipeline/scripts/superflow-archive.sh <explicit-archived-dir> --apply
+```
+
+Moved directories resume only remaining annotations and the original state
+transition, retaining validate/guard. Correct done + archived state returns
+read-only idempotently. Nonstandard tasks keep the existing state-only fallback.
+Check actual state.yaml, technical/design/plan annotations, and output; missing
+or conflicting facts remain blocked. No automatic commit/push/merge, repeated
+OpenSpec merge, or second closeout state machine.
+
 ## Rules
 
 - Do not archive if verification failed or is only partially verified unless

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

@@ -5,6 +5,13 @@ description: Use when confirmed requirements or OpenSpec artifacts need SDD cont
 
 # SDD Docs
 
+## Test plan entry
+
+Before writing tests.md, read the [test guide](../superflow-pipeline/references/test-guide.md).
+Reuse project tests and environments, map affected behavior to signals, and freeze
+cases, actual backends, mockBoundary, commands, and assertions here. Implementation
+inherits the plan; required database verification is not an implementation-time choice.
+
 For full document delivery, read and apply
 [requirement × real-entry review](../superflow-pipeline/references/document-review-coverage.md).
 Extend the existing three-round receipt with original-source, real-caller,
@@ -16,6 +23,12 @@ created the base OpenSpec artifacts. This skill is an SDD contract-doc wrapper;
 it must not replace the installed OpenSpec skills for core artifact generation
 and must not generate implementation prompts.
 
+For cross-round checks sensitive to commands/directories/invocation environment,
+freeze argv, relative cwd, and selected non-secret keys under the
+[executionContext contract](../superflow-pipeline/references/document-review-coverage.md#declared-execution-context-and-evidence-reuse).
+Historical unbound proof does not automatically satisfy new-context completeness.
+
+
 ## OpenSpec First
 
 For new OpenSpec document generation, invoke `$openspec-propose` first. The

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

@@ -5,6 +5,19 @@ description: Use when SDD/OpenSpec contract docs and Superpowers technical desig
 
 # SuperFlow Implement
 
+## Verification contract inheritance
+
+Before generating prompts, read the [test guide](../superflow-pipeline/references/test-guide.md).
+Inherit frozen tests.md cases, commands, actual backends, and assertions; require
+implementers to check them before editing, execute them, and record results. Missing
+signals or real-environment obligations return to superflow-docs, not a second plan.
+
+Prompts inherit frozen executionContext only. Execution entries generate actual
+cwd/selected environment hashes for raw-event/receipt checks; Agents do not fill
+expected observations. Missing bindings or changed contexts return to the document
+owner or affected reruns without rewriting historical successful records.
+
+
 ## Role
 
 This phase turns frozen contracts and source-level technical design into safe

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

@@ -3,6 +3,12 @@ name: superflow-pipeline
 description: Use when a user asks for the SuperBridge Flow, SDD, OpenSpec, requirements clarification, contract docs, design docs, implementation prompts, verification, archive, or which SuperBridge Flow phase to run.
 ---
 
+## Canonical test guidance entry
+
+Read [test-guide.md](references/test-guide.md) for test documentation, implementation
+preparation, or delivery review. Documents freeze required signals; implementation
+inherits and review verifies. Mock examples cannot override canonical DB contracts.
+
 # SuperBridge Flow Pipeline
 
 When maintaining Superflow CLI itself, first read repository-root

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

@@ -18,3 +18,6 @@ Use this when designing a new module or a cross-service change.
 
 Do not justify a design only because code can call another module. Prove that the
 call direction matches ownership and the existing architecture contract.
+
+Freeze signals using [test-guide.md](test-guide.md) and declare isolation using
+[mock-strategy-guide.md](mock-strategy-guide.md); substitute engines cannot close required real DB proof.

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

@@ -1,5 +1,12 @@
 # Batch Prompt Template
 
+Inherit verification only from tests.md and read [test-guide.md](test-guide.md).
+Apply startup, API, DB, and team checklists to frozen applicable cases; give source
+reasons for inapplicability, keeping missing required environments blocked. Reuse
+healthy instances matching the tested build; load new code/configuration before
+verification. Independently inspect raw evidence; implementers rerun invalidated
+or contract-required paths, not every environment merely because roles changed.
+
 ## Header
 
 - Batch: P{n} - {name}

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

@@ -176,3 +176,35 @@ boolean differs from number (true cannot prove one affected row), including nest
 arrays/objects. Documents and independent review choose business keys and fields.
 
 Git delivery compares normalized index objects for tracked report dependencies (receipts, raw events, builds, source, schema/contracts). A working-tree-only repair does not prove the commit snapshot. Private untracked evidence is not forced into Git; independent review still determines source/build applicability.
+
+## Declared execution context and evidence reuse
+
+Reuse coverage/receipt v1. When reusing checks sensitive to commands, working
+directories, or invocation environments, the document owner freezes tests.md and
+its case `executionContext={argv:[arguments],cwd:directory relative to change,environmentKeys:[names]}`.
+argv is nonempty and explicit; cwd is relative without drive prefixes or absolute
+paths. Task permissions and source/contracts still define read scope: cwd grants
+no additional access. Implementers cannot redesign this contract.
+
+Supported keys are PATH, PATHEXT, NODE_ENV, NODE_OPTIONS, LANG, LC_ALL, TZ, JAVA_HOME.
+Select only keys affecting this verification command. Passwords, tokens, account
+credentials, and full environments never enter contracts/receipts. Use project
+verification entries with runtime authentication; never put secrets in argv/docs.
+Absent and empty differ: each digest is UTF-8 SHA-256(JSON.stringify(string or null)).
+Receipts and raw events record
+`executionContext={cwd:actual canonical absolute directory,environmentSha256:{selectedName:digest}}`.
+Actual execution entries generate observations, not Agents filling expected values.
+
+Existing lint compares actual command.argv with frozen argv, receipt/event context,
+cwd with the frozen directory relative to the current change, and selected hashes
+with its current invocation environment. Run lint in the tests.md invocation
+context. Unselected environment changes do not invalidate proof; selected keys,
+commands, directories, source, builds, or targets changing prevent old proof from
+closing current complete PASS. This does not prove remote-service startup
+environments: engines, production chains, and sufficiency need independent review.
+
+Historical contracts without the field retain existing source/build/entry checks
+and their conclusions, without claiming this new context verification. Declared
+contracts with missing/malformed/mismatched observations need evidence, not editing
+old observations to expectations. Contract changes return to the document owner
+for renewed review rather than weakening execution checks.

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

@@ -63,3 +63,11 @@
 - DB/log evidence
 - Hook output
 - Blocked or skipped cases with reasons
+
+## tests.md: frozen verification signals
+
+Select applicable signals using [test-guide.md](test-guide.md), keeping project level numbers.
+Table: `Change/risk | Case ID | Signal | Actual environment/backend | Command | Assertion | Evidence path | Inapplicability reason/blocker`.
+Database layers inherit only `testLayer` / `mockBoundary` from
+[document-review-coverage.md](document-review-coverage.md). Reuse project scenario
+regression assets for critical business flows and bug reproductions.

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

@@ -1,5 +1,16 @@
 # Implementation Prompt Template
 
+For code-quality review read [reviewer-checklist.md](reviewer-checklist.md):
+select depth from actual impact, use isolated independent views, and have the
+main Agent verify and merge findings. Templates do not redefine risk or agent counts.
+
+Inherit verification only from tests.md and read [test-guide.md](test-guide.md).
+Apply startup, API, DB, and team checklists to frozen applicable cases; give source
+reasons for inapplicability, keeping missing required environments blocked. Reuse
+healthy instances matching the tested build; load new code/configuration before
+verification. Independently inspect raw evidence; implementers rerun invalidated
+or contract-required paths, not every environment merely because roles changed.
+
 Use this as the prefix for every implementation prompt.
 
 ## Context Drift And State Inheritance

package/assets/skills-en/superflow-pipeline/references/mock-strategy-guide.md

@@ -1,16 +1,46 @@
-# Mock Strategy Guide
+# Mock Strategy and Boundary Guide
 
-Mocks are allowed for isolation, not for claiming real integration.
+## Scope and source of truth
 
-## Labels
+Read for isolation design or substituted-evidence reporting. Select signals with
+[test-guide.md](test-guide.md). Database layers, mockBoundary, and execution
+receipts inherit only
+[document-review-coverage.md](document-review-coverage.md#database-layer-contract).
+This guide describes isolation, not permission to reduce frozen real acceptance.
 
-- Mock verification: dependency replaced or simulated.
-- Test endpoint verification: local helper endpoint or bypass path.
-- Real-entry verification: production-like user, device, callback, job, MQ,
-  client, or third-party entry.
+| Scenario | Isolatable boundary | Proven scope / remaining obligation |
+|---|---|---|
+| Pure logic unit test | Data-access/HTTP/MQ dependencies outside tested logic | Branches, parameters, failure handling; not real SQL or persistence |
+| Required persistence/transaction/CAS | External clients in mockBoundary.allowed | Never mock production Service/Mapper; execute production statements on the actual same-engine DB |
+| External payment/SMS/device | Contract-approved clients, sandboxes, simulated messages | Local handling; real capabilities need separate sandbox/real-entry proof or blockers |
+| MQ/Redis/OSS | Interface boundaries for pure logic | Memory queues, local cache/files cannot close real protocol, locking, persistence, or external-chain requirements |
 
-## Report Rule
+Actual same-engine Docker/Testcontainers databases are not mocks. Reuse when the
+frozen environment permits; never substitute for a required shared environment.
+H2/SQLite cannot replace MySQL dialect, locking, transaction, or persistence
+semantics. Without a DB preserve logic proof and mark required DB cases
+BLOCKED/PARTIAL.
 
-Keep these labels separate in test-report.md. Mock-only evidence cannot close a
-requirement that tests.md marks as L3/L4, real-entry, third-party, DB, or log
-verified.
+## Declaration and reporting
+
+Record actual capability, replacement object, mockBoundary, assumptions, proven
+scope, unverified scope, real verification commands/blockers, and evidence paths
+in existing tests.md / test-report.md. Separate `Mock verification`, `Test endpoint
+verification`, and `Real-entry verification`. Auxiliary logic cases may pass;
+mock-only cannot close required database or real-chain cases of the same entry.
+
+## Example: isolated payment client, actual persistence
+
+When the contract permits isolating PaymentClient, return a fixed success response
+to the **real** business Service and Mapper. On frozen MySQL, assert order-ID
+before/after, amounts, state, and required side effects. This proves handling and
+persistence, not actual gateway charging; verify charging separately or report a
+blocker. A pure Service unit test may mock Mapper but reports logic only, never
+successful database integration.
+
+## Prohibited
+
+- Mocking the tested subject or production Service/Mapper in required DB cases.
+- Replacing business/DB-value assertions with fixed success, counts, HTTP 200, or nonzero affected rows.
+- Mixing substituted and real evidence or counting skipped/unexecuted cases as complete passes.
+- Silently changing frozen backends, weakening assertions under delivery pressure, or leaving mocks in production.

package/assets/skills-en/superflow-pipeline/references/orchestration.md

@@ -1,5 +1,16 @@
 # Workflow Orchestration
 
+For code-quality review read [reviewer-checklist.md](reviewer-checklist.md):
+select depth from actual impact, use isolated independent views, and have the
+main Agent verify and merge findings. Templates do not redefine risk or agent counts.
+
+Inherit verification only from tests.md and read [test-guide.md](test-guide.md).
+Apply startup, API, DB, and team checklists to frozen applicable cases; give source
+reasons for inapplicability, keeping missing required environments blocked. Reuse
+healthy instances matching the tested build; load new code/configuration before
+verification. Independently inspect raw evidence; implementers rerun invalidated
+or contract-required paths, not every environment merely because roles changed.
+
 SuperBridge Flow is a stateful orchestrator, not just a set of installed skills.
 
 ## Ownership

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

@@ -1,5 +1,14 @@
 # Quality Gate Checklist
 
+For code-quality review read [reviewer-checklist.md](reviewer-checklist.md):
+select depth from actual impact, use isolated independent views, and have the
+main Agent verify and merge findings. Templates do not redefine risk or agent counts.
+
+Check frozen signals and applicability using [test-guide.md](test-guide.md).
+Missing required environments remain blocked; inapplicability cannot remove frozen
+gates. Reuse healthy instances matching the tested build; independently inspect
+raw evidence and have implementers rerun invalidated or contract-required paths.
+
 ## Documentation Gate
 
 - Requirements processed feature by feature and frozen.

package/assets/skills-en/superflow-pipeline/references/reviewer-checklist.md

@@ -1,5 +1,124 @@
 # Reviewer Checklist
 
+## Five-axis review and isolated context (canonical entry)
+
+Use for ordinary code review, Quick verification, full SDD, and managed Host
+review. Inputs are current changes, confirmed contracts, applicable path rules,
+and raw evidence. Outputs reuse reviewer reports or existing Host review JSON.
+This checklist owns axes, depth, isolation, and finding verification;
+superflow-verify routes execution. Check requirement/design conformity against
+existing contracts without creating another requirements-review entry. Scripts
+check paths, state markers, and anchors, not review sufficiency. The main Agent /
+Host owns actual risk and the final verdict.
+
+### Axis coverage
+
+| Axis | Focus | Minimum evidence |
+|---|---|---|
+| security | Authentication/authorization, injection, sensitive information, external input | Actual entry, parameter binding, permission call path |
+| performance | Query scope/N+1, scale, CPU/memory/I/O, resource limits | Execution path and scale; benchmarks only when risk warrants |
+| correctness | Boundaries, recovery, state, transactions, concurrency, idempotence | Real call/write path, assertions, failure paths |
+| maintainability | Duplication, naming, complexity, exception handling, test seams | Existing reuse points, source, test boundaries |
+| architecture | Module ownership, call direction, contract compatibility, abstraction | Callers/consumers and ownership evidence |
+
+Record CHECKED / NOT_APPLICABLE / BLOCKED and source/evidence per axis. CHECKED
+means examined, not defect-free. One reviewer may cover all axes; do not require
+five agents. Specialists cover assigned axes; the main Agent merges coverage and
+fills gaps. Unassigned/unread is not inapplicable. Full SDD real acceptance remains.
+
+### Select depth from actual impact
+
+`superflow review-coverage` emits `risk.basis=path-hint` and
+`risk.requiresSemanticAssessment=true`. The main Agent reads changes, actual
+callers, and write/consumer paths, recording hint tier, actual tier, source
+anchors, and adjustment reasons. Names, line counts, and implementer claims do
+not determine risk. Unknown risk gets at least medium investigation; inability
+to judge means NEEDS_CONTEXT.
+
+| Actual impact | Depth |
+|---|---|
+| Small scope with verified absence of contract/write/concurrency/security/cross-module effects | Low, inline allowed; still cover applicable axes |
+| Other changes with known scope | Medium, one isolated independent reviewer |
+| Evidenced public-contract break, migration/data consistency, locks/shared state, security boundary, or cross-module impact | High, independent review plus focused views for named risks; fan out only for independent risk clusters when the Host supports it |
+
+Example: a parameterized SELECT filter with unchanged contract/schema/write path
+and checked consumers can move from Mapper path hint high to actual medium. An
+ordinary file adding atomic claims/shared-state writes moves from path hint low to
+actual high. Confirm against current source rather than applying example labels.
+High does not prescribe agent counts, model names, or providers; use native Host
+configuration. Record user depth overrides without removing required scope,
+contract obligations, or known risks.
+
+### Isolated bundle and dispatch
+
+The main Agent prepares this bundle in a temporary directory and uses native
+subagents without implementation chat history (`fork_turns=none` when supported).
+If unavailable, prepare the same bundle for an independent reviewer and report
+that independent review has not run. Self-review cannot be relabeled independent
+or counted as complete independent coverage.
+
+1. Confirmed goal, scope, exclusions, actual contract paths, review questions;
+   label implementer claims unverified.
+2. Baseline/head or worktree state, exact diff, file inventory, related bundles;
+   diff statistics alone are insufficient.
+3. Applicable path rules, relevant source/caller/consumer paths, necessary
+   environment and raw test evidence paths.
+4. Actual risk assessment, assigned axes/files, this checklist, four-state and
+   anchored report requirements.
+
+Include only necessary text/paths, not entire repositories, personal rule
+folders, credentials, or chat history. Respect task read permissions. Start from
+diff and expand to related callers only for named risks, recording why. Bundle /
+source / contract drift yields NEEDS_CONTEXT rather than reviewing old context
+against current code. Reviewers are read-only: no source edits, application
+management, business DB operations, or nested supervision. New runtime evidence
+returns to the implementer.
+
+### Main Agent verification and merge
+
+Read all reports, coverage, findings, and concerns. Re-read each file:line, callers,
+frozen contracts, and corresponding raw test evidence; attempt to disprove claims
+with actual source. Green tests alone neither accept nor reject a finding.
+Deduplicate by root cause + affected path + business consequence, keeping reviewer
+provenance and full impact. Do not merge solely by line number, wording, or
+severity. Resolve conflicting judgments from evidence, not majority vote.
+
+Record accepted / rejected / needs-evidence with reasons. Unsupported claims remain
+unconfirmed rather than receiving invented severity. Severity follows actual
+impact; separate advice from blocking defects. Do not force generic abstractions
+without another caller or contract requirement. Once every axis and included file
+has coverage, submit all material findings together. Managed work retains existing
+finding IDs / acceptanceContractRefs, protocols, budgets, and state owners.
+Subagent reports do not directly promote pass; format checks do not prove code
+correctness. Rerun only invalidated or contract-required evidence.
+
+### Reviewer report shape
+
+Reuse the four-state report, not another machine protocol. Managed reviews keep
+these records in temporary reports and project the result into existing Host
+review JSON summary/findings/coverage. `--report` checks existing markers and
+anchors only; the main Agent verifies axes, actual impact, and conclusions. Keep
+historical reports without axis records, but do not call them complete under this
+guide.
+
+```markdown
+DONE
+## Impact
+Path hint / actual depth / source evidence / adjustment / diff and contract version
+## Axes
+Axis | CHECKED / NOT_APPLICABLE / BLOCKED | File scope and evidence
+# Fill security / performance / correctness / maintainability / architecture
+## Findings
+- src/example.ts:12: [axis][severity] cause, consequence, proof, repair and acceptance
+# Use None without findings; never a placeholder bullet
+## Concerns
+Unresolved questions and missing proof; required for DONE_WITH_CONCERNS
+```
+
+Existing specialist checks remain path-scoped; inapplicable checks do not invent
+runtime obligations or remove frozen requirements. They detail axes without
+owning risk, dispatch, or final conclusions.
+
 ## Data Scale And Processing Cost
 
 - For data-intensive paths, are current/expected data scale and growth
@@ -12,7 +131,7 @@
 
 - Does the implementation match api.md, design.md, and tests.md?
 - Are all required files present and cross-linked?
-- Is handoff_hash current and repeated in prompts/report?
+- Is the frozen handoff hash current in its canonical state file? Do not duplicate raw hashes in report bodies.
 - Did Superpowers technical design cover source-level HOW?
 - Were field/status and architecture-boundary risks checked?
 - For monetary changes, were calculation and settlement states separated, were
@@ -42,3 +161,5 @@
 - Are mock-only results clearly labeled?
 - Did workers stay inside allowed file boundaries?
 - Did hooks and guard scripts pass?
+
+Use spaces and explicit closure for report container fences. Tab-delimited list/quote fences currently fail structural verification: normalize report formatting without using an earlier DONE/PASS to bypass it. Preserve tabs in original execution logs; do not rewrite evidence for formatting.

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

@@ -28,6 +28,27 @@ canonical_sources:
 - If this document conflicts with canonical sources, stop and return to
   `$superflow-docs`; do not let implementation prompts carry the conflict forward.
 
+## Directory Changes
+
+List Created / Modified / Deleted / Not created modules and key files, with
+responsibility and reuse evidence. Trees or lists are fine; annotate action,
+owner, and reason rather than names alone. Use None for empty categories.
+Not created records considered modules/helpers/caches/state/parallel entries and
+why they were rejected. Record implementation-local helper/method edits without
+automatically expanding business scope. Details within confirmed modules that
+preserve contracts need no new requirement confirmation; frozen HOW repairs still
+return to the document owner for handoff refresh and existing review. New owners,
+cross-module dependencies, allowed path scope, or acceptance obligations return
+to clarification/docs before coding. Runtime protections, source coverage, and
+existing approval rules remain; this inventory creates no parallel state.
+
+| Action | Module/file | Owner and responsibility | Reuse/evidence or rejection reason |
+|---|---|---|---|
+| Created | None / `<path>` | | |
+| Modified | None / `<path>` | | |
+| Deleted | None / `<path>` | | |
+| Not created | None / `<candidate>` | | |
+
 ## Source-Level HOW
 
 | Requirement/Scenario | Code anchor | Current behavior | Target HOW | Files/methods | Risk |

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

@@ -1,5 +1,10 @@
 # Test Execution Template
 
+Read [test-guide.md](test-guide.md) first and inherit frozen tests.md / Quick Spec
+signals. Fill applicable cases; give source reasons for inapplicable fields and
+BLOCKED/PARTIAL for unavailable required environments. Existing coverage/receipts
+check facts; template examples never redesign tests or reduce frozen gates.
+
 Use the environment frozen in tests.md; do not substitute local containers or
 mocks for an explicitly required shared development environment. When the user
 requires every endpoint to be exercised, freeze an endpoint/role/scenario matrix,

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

@@ -1,16 +1,110 @@
-# Test Guide
+# Test Selection and Verification Loop
 
-## Levels
+## Scope and ownership
 
-- L0: unit test.
-- L1: component test.
-- L2: integration with real infrastructure such as Testcontainers.
-- L3: API or message contract test with executable command.
-- L4: real external entry such as callback, device, scheduler, client, or
-  third-party sandbox.
+Read when generating tests.md, starting implementation, repairing findings, or
+verifying delivery. Inputs are confirmed requirements, source changes, existing
+project tests, and frozen contracts. Write outputs into existing tests.md / Quick
+Spec and test-report.md. Documentation-only work checks its contracts; pure
+functions check their seam without inventing application or database requirements.
 
-## Rule
+superflow-docs freezes the plan; the implementer executes and records evidence;
+superflow-verify / Host judges sufficiency and historical applicability. Existing
+coverage/receipt/lint checks deterministic facts; the existing state machine owns
+state. Database machine contracts come only from
+[document-review-coverage.md](document-review-coverage.md#database-layer-contract).
+Reuse testLayer, mockBoundary, and execution-receipt.v1, without another evidence
+format or level system. Superflow distributes this guide; no ake verification
+skill installation or .ake memory is required.
 
-When tests.md requires L3/L4, test-report.md must include real command,
-response, DB/log assertion, and final state evidence. Unit tests alone do not
-close the requirement.
+## Select signals before implementation
+
+Search existing tests, build wiring, environment configuration, and project rules.
+Reuse seams, commands, and tools. Before production edits, map each affected
+behavior to these signals and freeze case IDs, commands, assertions, and evidence
+paths. Give source reasons for inapplicable signals. Missing environments for
+required cases mean BLOCKED/PARTIAL, never inapplicable. Implementers cannot
+remove frozen obligations; omissions return to the document owner.
+
+| Change/risk | Signals to freeze |
+|---|---|
+| Pure function or local algorithm | Narrow unit checks, boundaries/failures, applicable build and static checks |
+| Component wiring or configuration | Above checks plus real application/context startup and readiness |
+| SQL, Mapper, persistence, transactions, CAS, data-driven behavior | Logic checks plus production statements against the same database engine; full SDD also covers real consuming entries |
+| API, public fields, authentication | Existing contract tests/snapshots plus affected real entries; establish new contract baselines |
+| New capability spanning API, business logic, storage | Build, unit, wiring, real database, API contract, at least one real main flow |
+| Bug fix | Same symptom RED → GREEN plus affected regression; environment failure is not business RED |
+| MQ, devices, callbacks, cache, third-party semantics | Freeze real protocol/backend/entry verification and isolatable boundaries; missing environment remains blocked |
+| Report format or test isolation only | Check affected contracts/evidence without automatically rerunning unrelated business flows |
+
+Keep project case level numbering; do not import ake L1/L3/L5/L7/L8/L10 numbers.
+Database testLayer and entry acceptance level are separate dimensions; a level
+label cannot hide a missing real backend.
+
+## Mocks and environments
+
+The [Mock guide](mock-strategy-guide.md) describes isolation boundaries. Logic
+unit tests may mock data access, but cannot prove SQL, transactions, or persistence.
+Required database cases cannot mock production Service/Mapper; mockBoundary
+freezes allowed external clients. H2/SQLite cannot substitute for MySQL proof.
+A real same-engine container database is not a mock. Freeze engine/major, schema
+provenance, production statements, and cleanup. Use a required shared environment;
+otherwise use existing container infrastructure when the contract approves it.
+Without an executable environment, preserve logic evidence and mark real database
+cases BLOCKED/PARTIAL rather than reducing acceptance.
+
+## Retained business scenario tests
+
+Prefer repeatable project-native regression tests for critical business flows and
+bug reproductions. Reuse directories, fixtures, authentication, DB helpers, and
+execution scripts. Extend equivalent tests instead of building another scenario
+framework or public helper. Keep pure logic at the lowest adequate layer. Java
+may reuse existing JUnit/RestAssured/JdbcTemplate; other stacks use native tools,
+without mandatory Java dependencies.
+
+Assert concrete business response values, same-business-ID database state, and
+contract-required messages/logs/side effects separately. Freeze before/after,
+affected rows, and unchanged non-target records under the canonical contract.
+HTTP 200, non-null values, invocation counts, or affectedRows=1 alone do not prove
+correct persistence.
+
+Make subjects unique per run/case; resolve stable base data by business key or
+logical name and fail during setup when missing. Reuse project environment and
+auth commands; record credential sources rather than passwords/tokens in source
+or docs. Never automatically seed or delete shared base data. Freeze data creation
+permissions, ownership, cleanup scope, and failure cleanup. Use existing tags,
+profiles, or scripts to run environment-dependent scenarios separately from unit
+checks. Grouping does not skip required delivery cases: explicitly run required
+groups and check execution counts. Cases do not depend on order or share mutable
+subjects.
+
+## Execute, review, and inherit evidence
+
+Run narrow tests first, then frozen build/startup/real-entry commands. Read exit
+codes, counts, and raw output; fill case evidence using the
+[execution template](test-execution-template.md). Never fit frozen assertions to
+wrong output. Passing conclusions cover only executed layers; zero cases, skipped,
+and unexecuted checks cannot become PASS.
+
+For repairs, map current changes → invalidated evidence → rerun commands.
+Production code, SQL, configuration, authentication, public contracts, runtime
+entries, or environment changes invalidate affected proof. Report formatting
+alone does not automatically invalidate prior runtime results. Historical evidence
+must match source/build, backend/entry, and contract; independent review judges
+applicability. It cannot authorize another source version. Reuse healthy instances
+matching the tested build; restart and reverify when code/configuration/identity
+mismatches. Stop only through frozen owner verification and cleanup entry points,
+never broad pkill/killall. Pure functions need no process; required real entries
+cannot be waived. Reviewers inspect source and raw evidence read-only; implementers
+own execution and cleanup. Independent review does not mean mechanical full reruns.
+
+## Repair failures
+
+Reproduce case preconditions and inspect actual SQL/bindings, transaction
+boundaries, responses, and logs. For DB failures first inspect production
+statements, written fields, schema, and same-ID before/after values; do not blindly
+add transaction annotations or replace Mapper methods. Run the same path and
+affected regression after repair. Design changes first repair canonical contracts.
+Do not skip failures, weaken assertions, or hide blockers.
+
+For cross-round checks sensitive to commands/directories/invocation environments, freeze executionContext under [declared context](document-review-coverage.md#declared-execution-context-and-evidence-reuse). Keep historical proof without calling unbound records complete under a new context.