The running application, migrations, configuration, and tests are authoritative. README.md
describes the product; docs/api/openapi.json is the generated API contract; files in docs/ are
reserved for stable user or operator behavior. Git history is the record of old designs and
implementation decisions.
Do not create tranche reports, freeze records, implementation records, evidence inventories, checkpoint/hash ledgers, or separate design/review documents unless the user explicitly asks for that deliverable. Do not make ordinary implementation wait for invented approval phases. A self-review is part of implementation; an “independent review” is a separate task only when the user requests it.
- Start with
git status --branch --short, then read the nearest runtime code, tests, migrations, and applicable documentation. Preserve unrelated user changes. - State the concrete behavior being changed and trace the existing call path before designing new abstractions.
- Implement the smallest end-to-end vertical slice in the existing runtime path. Prefer extending established services and value objects over a parallel namespace or inert foundation.
- Add or update tests that exercise the integrated behavior. A test suite for code that no production path can reach is not evidence that a feature is implemented.
- Run checks proportional to the touched surface, inspect the complete diff, and report the result, tests, and remaining risks concisely.
Make reasonable reversible assumptions and keep moving. Ask first only when a missing product decision would materially change behavior, when external coordination is required, or before a destructive/financial action that the user has not already authorized.
Do not stage, commit, push, open a PR, mutate real wallets/nodes, broadcast transactions, reset a database, or delete volumes unless the user explicitly requests that action. Read-only inspection is allowed when it is relevant and safe.
Work in one agent by default. Use subagents or formal handoffs only when the user explicitly asks for delegation or parallel agent work.
- “Tranche” and “slice” are planning labels, not namespaces or lifecycle gates. Each slice must leave a working integrated path; do not add parallel tranche-specific production directories.
- Avoid speculative registries, versioned
V1duplicates, custom protocols, and conditional migrations unless a current caller and concrete invariant require them. - Keep migrations deterministic. Feature flags may gate runtime behavior, but should not make the schema silently differ between otherwise identical deployments.
- Put durable invariants in database constraints and focused code; put examples and edge cases in tests. Do not duplicate these line-by-line in Markdown.
- Add an architecture decision record only for a genuinely hard-to-reverse cross-system decision and only when requested. Keep it short: context, decision, consequences.
- Delete temporary investigation artifacts once their useful result is represented by code, tests, an issue, or stable operator documentation.
Exact-decimal changes must follow the real money path: request validation → provider/RPC parsing →
quote calculation → persistence → API serialization → monitoring → settlement/send boundary.
Reuse or consolidate the existing SettlementDecimal/custody decimal approach instead of building
a disconnected decimal subsystem.
- Accept monetary inputs as validated decimal strings and never introduce a float boundary.
- Parse external numeric tokens without an intermediate binary float.
- Define scale and rounding once at the business boundary; persisted/replayed values require exact scale with no silent rounding.
- Keep RPC method/parameter and response validation close to the RPC adapter that uses it.
- Test public behavior plus critical provider/RPC and persistence boundaries.
Backend code lives in app/, HTTP routes in routes/api.php and routes/web.php, Vue code in
resources/js/, and schema changes in database/migrations/. Tests are organized by intent under
tests/Unit, tests/Feature, and tests/Integration. Prefer small domain services over
controller-heavy logic and align PSR-4 class names with file paths.
The application runs in Laravel Sail. Run PHP, Composer, Artisan, Pint, application tests, and
project Node commands through ./vendor/bin/sail; do not use host PHP or Composer results as
project verification. Start only the services needed for the current task. Do not start blockchain
node profiles or invoke real-RPC integration merely to satisfy an unavailable test dependency.
Follow .editorconfig (UTF-8, LF, four spaces; two for YAML) and format touched PHP with
./vendor/bin/sail pint --dirty.
Use the narrowest relevant checks while iterating, then broaden according to risk:
./vendor/bin/sail test
./vendor/bin/sail composer test:fast
./vendor/bin/sail npm run build./vendor/bin/sail composer test:integration performs real-RPC work and requires explicit intent
plus verified test networks. Run ./vendor/bin/sail composer test:all when settlement, forwarding,
signing, or RPC integration changes and that external test authority is available. Never weaken
production behavior to make an unavailable real-node test pass.
Before handoff, run git diff --check and inspect git status --branch --short. A concise final
answer should name changed behavior/files, exact checks run, failures or skipped checks, and any
real remaining risk. Do not paste giant reports or routine full diffs unless asked.
Never commit .env secrets. Keep FORWARDING_ENABLED=false, custody/payout gates false, and
local/dev signing modes out of production defaults. Treat integration nodes and configs under
nodes/ as development infrastructure; mainnet funds and production databases are always out of
scope without explicit, verified authorization.