@zktx.io/sui-mcp 0.5.0

package/docs/AGENT_DEVELOPMENT_POLICY.md

@@ -0,0 +1,815 @@
+# Agent Development Policy
+
+This document contains binding development, review, documentation, and
+source-of-truth policies for coding agents working in this repository.
+
+Read `AGENTS.md` first. Read this document whenever the task touches a boundary
+listed under `Required Detailed Policies` in `AGENTS.md`. These rules are not
+optional guidance and must not be weakened to make a task easier.
+
+## Repository Map
+
+Target repository structure:
+
+- `src/core/`: action-neutral intent, plan, review check, and result primitives.
+- `src/core/evidence/`: natural-language intent evidence helpers and
+  evidence-boundary primitives.
+- `src/adapters/`: protocol-specific adapter implementations. Shared review,
+  material, ownership, simulation, acceptance, and handoff contracts should stay
+  protocol-agnostic unless a concrete implementation proves otherwise. DeepBook
+  is the current signable swap adapter implementation; additional
+  protocol support must be added through adapter contracts rather than a
+  custom-only product path.
+- `src/mcp/`: MCP server and tool definitions.
+- `src/review-server/`: local review HTTP server and session APIs.
+- `review-app/`: the Settings page and shared display helpers/styles.
+- `src/mcp-ui/`: internal Account, Receipt, Chart, Connect and Review cards, their
+  common lifecycle and view code.
+- `src/runtime/shared/`: authenticated server ownership and MCP forwarding.
+- `registry/`: local policy, allowlists, aliases, and generated mainnet metadata.
+- `protocols/`: AI-readable protocol notes.
+- `scripts/`: utility scripts for state inspection, registry generation, and
+  reports.
+- `docs/UTILITY_INDEX.md`: index of reusable utility scripts.
+- `.WORK/`: local planning notes; ignored by Git.
+
+Inspect the actual repository before assuming any path exists. If the
+repository differs from this map, the repository is the current fact and this
+section should be updated when the difference is intentional.
+
+## Communication Rules
+
+- Answer with verified facts and concise conclusions.
+- Do not waste tokens on excuses, filler, or unsupported speculation.
+- Concise means selective, not truncated. Do not abbreviate content, terms, task
+  names, or status wording in documents, reports, or discussion when the
+  abbreviation can change, narrow, or obscure the meaning.
+- State uncertainty plainly when evidence is incomplete.
+- Separate facts, assumptions, and recommendations.
+- When work is missing, incomplete, removed, weakened, or previously overstated,
+  state that concrete fact directly. Do not relabel it as alignment, cleanup,
+  simplification, consolidation, follow-up, or a harmless tradeoff when the
+  verified fact is that required behavior was not implemented or was narrowed.
+- Use status labels and progress reports only when they name the actual state.
+  `blocked` must identify the blocking condition, `unverified` must identify the
+  missing verification, and a progress report must name completed subtasks and
+  remaining requirements. Do not use `partially complete` as a success state.
+  These labels and reports must not soften a defect, downplay a missed
+  requirement, or support a completion claim when completion criteria are unmet.
+- A scoped unit of work has no partial-success state. Progress can be reported by
+  naming completed subtasks, but that progress is not task success. The unit
+  succeeds only when every required behavior is implemented, every required
+  cleanup is done, and every verification point passes. Otherwise report the
+  unit as not complete and name the concrete blocker, missing requirement,
+  failed check, or unverified requirement.
+- Do not hide a defect to preserve momentum or protect prior work. If a previous
+  answer, plan, review, or commit claimed completion incorrectly, correct the
+  record explicitly.
+
+## Documentation Review
+
+When editing `AGENTS.md`, `README.md`, files under `docs/`, files under
+`protocols/`, or runtime-facing instruction and limitation text such as
+`src/mcp/serverInfo.ts`, do a first-reader pass before calling the work complete.
+
+Read the changed document as if you are a new agent or human with no prior
+conversation context. Verify that it communicates:
+
+- the product purpose or user problem the document supports;
+- what is implemented, planned, unsupported, or intentionally out of scope;
+- the authority and boundary of every tool, workflow, protocol term, number,
+  policy, or product claim it mentions;
+- what the reader should do, and what they must not infer.
+
+Separate current implementation, planned future capability, current-release not-yet-implemented behavior, and permanent no-goal statements. Do not place all four
+categories under wording such as "not yet possible" or "planned boundary" when
+that wording could make a permanent no-goal sound like a roadmap item, or make a
+planned future capability sound permanently unsupported.
+
+Public and runtime-facing documents must describe current product behavior,
+current tool contracts, and current unsupported boundaries only. Do not include
+implementation history, prior states, migration history, decision history,
+planning rationale, or "why we changed this" notes in README, `docs/`,
+`protocols/`, runtime instructions, MCP resources, tool descriptions, or
+user-facing strings. Keep that history in ignored `.WORK` notes.
+
+Two approved exceptions have a limited delivery purpose. README may carry a
+factual package/repository transition notice tied to installation, distinguishing
+planned destinations from completed publication. Reviewed English development
+records may live under `submission/ethglobal-tokyo-2026/`, with translations and
+retrospective summaries labelled as such. That directory is not product guidance,
+is never registered as an MCP resource, and is excluded from npm packages. These
+exceptions do not permit development history in other product/runtime documents
+or change `.WORK`'s role as ignored working material.
+
+If the intended meaning depends on prior chat, hidden context, vague shorthand,
+or local assumptions, rewrite it.
+
+Remove wording that is ambiguous, overly broad, contradictory, likely to make a
+reader overclaim product support, skip required verification, or optimize for
+size instead of quality.
+
+Write and review documents so a third-party reader with no Sui MCP
+background can understand and use the content without guessing.
+
+Use ordinary industry terms when they exist. Do not introduce project-specific
+terms, internal shorthand, or product labels when a plain description can say
+the same thing. If such a term is unavoidable because it is an existing API
+field, type name, command, or documented product surface, define it in plain
+language at first use and state exactly what it does and does not mean.
+
+Do not use words whose meaning can change based on when the reader sees them,
+which previous conversation they remember, or which nearby paragraph they
+connect them to. Replace context-dependent wording with explicit source, time,
+state, actor, tool, field, and unsupported-use statements.
+
+Do not rely on phrases that invite the reader or an AI client to fill gaps with
+imagination, such as unexplained "policy", "boundary", "gate", "support",
+"coverage", "readiness", "evidence", or "review" wording. Either replace the
+phrase with a concrete description or define the exact source, allowed use, and
+unsupported use.
+
+For MCP-facing documentation and runtime guidance, assume the connected AI
+client may follow wording literally. Prefer concrete tool names, response
+fields, and allowed conclusions over abstract warnings. If the document says an
+AI must not use a value for a conclusion, also identify the field that should be
+used instead.
+
+## Documentation Ownership
+
+Use this single responsibility schema when editing documentation:
+
+| Document | Owns | Must not own or claim |
+| --- | --- | --- |
+| `README.md` | Public first-entry document for product purpose, current release boundary, setup path, and documentation map. | Detailed tool contracts, user-question workflows, internal planning history, or release-review matrices. |
+| `AGENTS.md` | Root development contract and non-negotiable product boundaries for coding agents working in this repository. | User setup instructions, feature catalogs, runtime-only AI-client answer behavior, or long-form policy details. |
+| `docs/AGENT_DEVELOPMENT_POLICY.md` | Detailed binding development, review, documentation, source-of-truth, and completion policies for coding agents. | User setup instructions, MCP API contracts, user-question playbooks, or runtime-only AI-client answer behavior. |
+| `docs/MCP_SETUP.md` | Installation, MCP client connection, first-use flow, local settings, and troubleshooting. | Long API behavior rules, field contracts, response wording rules, or user-question playbooks. |
+| `docs/MCP_TOOLS.md` | MCP API reference for tool contracts, response fields, statuses, follow-up fields, and output boundaries. | Installation procedures or user-question playbooks. |
+| `docs/AGENT_BEHAVIOR.md` | Answer playbook for user-question flows, tool selection, and response wording. | Tool schemas, field contracts, response-field definitions, or install procedures. |
+| `docs/WALLET_CONNECTION.md` | Approved wallet connections, active-account read context, private SDK persistence and the distinction between connection and per-transaction approval. | Login, authentication, custody, authority to approve a transaction, full review/API contracts or setup ownership. |
+| `docs/TRANSACTION_ACTIVITY_LOG.md` | Local transaction activity storage, scan, and summary boundaries. | Complete wallet history, P&L, route recommendations, transaction-building input, signing data, or signing readiness. |
+| `docs/UTILITY_INDEX.md` | Manual utility and source-checkout script boundaries, including the distinction between utilities, MCP tools, and packaged product commands. | Promotion of utility scripts as MCP tools, review-time simulation, packaged product commands, transaction builders, signing-readiness signals, or wallet authorization evidence. |
+| `docs/LOCAL_DB_ARCHITECTURE.md`, `docs/SDK_API.md`, and other architecture or evidence notes | Specific implementation boundaries, pinned source facts, storage facts, and source-verification notes. | Future support presented as current product functionality. |
+| `docs/FRONTEND_POLICY.md` | Review-app frontend implementation policy and local UI boundary rules for coding agents. | Backend API contracts, MCP tool contracts, or user setup flow ownership. |
+| `docs/golden-scenarios/*.md` | Release-review scenario matrices, golden answer shapes, allowed conclusions, and forbidden conclusions. | MCP API contracts or replacement definitions for response fields. |
+| `protocols/*.md` | Protocol references and promotion-gate research notes only. | Runtime registries, supported-protocol lists, live liquidity sources, route recommendations, signing-readiness signals, or support declarations. |
+| `submission/ethglobal-tokyo-2026/` | Reviewed English development records for the approved external delivery. | Product rules, runtime guidance, MCP resources, or npm package contents. |
+| `.WORK/` | Ignored local planning notes. | Product-facing rules unless moved into README, AGENTS, docs, protocols, tests, or code comments. |
+
+Do not remove all repetition. These repeated boundaries are allowed when they
+protect readers on separate surfaces:
+
+- the top-level boundary against autonomous execution, private-key signing or
+  custody, venue ranking, route choice, silent settlement-token selection, fiat
+  cash-out, P&L and signing-readiness claims; user-approved wallet signing and
+  independently verified backend submission are distinct supported operations;
+- the core answer path that `read.preview_intent_evidence.responseSummary` and
+  response-local `userAnswerUse.answerFields` identify fields for
+  USD-denominated coverage, balance-total, and shortfall answers;
+- the safety rule that separate DeepBook quote outputs are price estimates and
+  must not be combined into payment coverage or shortfall conclusions.
+
+Do remove or rewrite duplication when it creates conflicting authority:
+
+- The API reference and answer playbook must not define the same tool contract
+  in different words. Tool contracts belong in the API reference; question flows
+  belong in the answer playbook.
+- API field meanings must not be reinterpreted in prose. If a document says a
+  field cannot support a conclusion, it must name the response field that should
+  be used instead when one exists.
+- Protocol Markdown must not read as a runtime registry, supported-protocol
+  list, live liquidity source, route recommendation source, or signing-readiness
+  signal.
+- Setup documentation must not copy long API behavior rules. It should link to
+  the API reference and answer playbook after the first-use setup flow.
+
+## Instruction Surface Ownership
+
+Keep development-time rules separate from MCP-injected agent guidance.
+
+Development rule surfaces are for contributors and coding agents changing the
+repository.
+
+They include `AGENTS.md`, `docs/AGENT_DEVELOPMENT_POLICY.md`, implementation
+notes under `docs/`, release-review matrices, protocol research notes, tests,
+and ignored `.WORK/` planning notes.
+
+They may define product invariants, implementation discipline, review criteria,
+and release gates. Clients do not reliably read them at runtime.
+
+MCP-injected or runtime-facing agent surfaces are what connected AI clients can
+actually discover through the server.
+
+They include:
+
+- `SERVER_INSTRUCTIONS` in `src/mcp/serverInfo.ts`;
+- MCP prompts in `src/mcp/prompts.ts`;
+- tool schemas and descriptions;
+- MCP resources registered from `src/mcp/resources.ts`.
+
+Runtime-facing resources currently include:
+
+- `README.md`;
+- `docs/MCP_SETUP.md`;
+- `docs/MCP_TOOLS.md`;
+- `docs/WALLET_CONNECTION.md`;
+- `docs/AGENT_BEHAVIOR.md`;
+- `protocols/deepbook-v3.md`;
+- `protocols/deepbook-margin.md`.
+
+When a behavior must influence AI client answers, put the actionable guidance in
+a runtime-facing surface and guard it with tests.
+
+`AGENTS.md` and this detailed policy may require that such a runtime-facing rule
+exists. They must not be the only places where an AI client is expected to learn
+user-answer behavior.
+
+Keep tool descriptions concise, literal, and instruction-free. Use server
+instructions, resources, prompts, schemas, output fields, and tests for behavior
+guidance.
+
+## Evidence Standard
+
+Do not work from imagination or unchecked assumptions.
+
+Before applying an external suggestion or plan:
+
+- investigate the claim;
+- check the current codebase, official docs, source code, or direct command
+  output;
+- separate verified facts from assumptions;
+- explain the evidence behind the recommendation;
+- do not apply the suggestion blindly.
+
+For Sui, DeepBook, MCP, wallet behavior, transaction building, SDK behavior, and
+dependency behavior, prefer official documentation, source code, and local
+inspection over memory.
+
+When official docs and the pinned installed SDK disagree, implementation must
+follow the pinned SDK/source actually used by this repository. Document the
+discrepancy.
+
+## Planning And Scope
+
+For non-trivial or boundary-changing work, compare alternatives before choosing
+a direction.
+
+Before implementation, identify:
+
+- what prerequisite work should already exist;
+- what must be inspected first;
+- what alternative development directions are available;
+- why the chosen direction is better for the current goal;
+- what risks or scope traps should be avoided.
+
+Plans must be grounded in confirmed objective facts. Distinguish current
+implemented work from unimplemented expansion, and do not make unimplemented
+possibilities look like supported functionality.
+
+Before answering a status, planning, review-readiness, commit-readiness, or
+next-task question, verify the same-turn disk facts that the answer depends on.
+At minimum, inspect tracked status, unstaged/staged diff summary, changed file
+names, untracked files, and the active roadmap or work note that owns the
+canonical task name. Do not reuse a clean/dirty/tree-status statement from a
+prior turn. If disk facts changed after a plan was written, treat the plan as
+stale until reconciled.
+
+For each specification-baseline requirement, identify the implementation surface
+and verification point before claiming the plan is executable. During
+implementation and final review, classify each baseline requirement as
+implemented, missing, weakened, or unverified.
+
+Do not silently drop, merge, rename, or weaken a baseline requirement because it
+is inconvenient, cross-module, time-consuming, or already partly covered by docs
+or tests.
+
+Do not introduce generalized abstractions for aesthetics, symmetry, or future
+possibilities before a concrete implementation proves that the verified boundary
+needs them.
+
+Do not use boundary control as an excuse to avoid necessary investigation. Do
+not use broad investigation as an excuse to expand product authority, add
+unrelated features, or delay a safe fix.
+
+When a request points to a specific file, line, review comment, or symptom, do
+not start by editing that spot. First inspect adjacent callers, callees,
+schemas, docs, tests, user flows, failure modes, and shared invariants. If
+inspection shows the pointed-at spot is the only affected boundary, state that
+finding and keep the edit narrow.
+
+## Development Discipline
+
+For every task:
+
+1. Inspect the current repository state first.
+2. Identify affected files, modules, interfaces, user flows, and docs.
+3. Check whether a source-of-truth implementation already exists before adding a
+   function, type, script, adapter, or registry entry.
+4. Reuse existing source-of-truth code when it exists. Do not create a parallel
+   helper with similar responsibility unless the existing source is demonstrably
+   wrong or too limited for the verified boundary.
+5. Add new code only when no suitable source exists or the existing source is
+   demonstrably insufficient.
+6. Do not duplicate existing logic, registries, or protocol metadata without a
+   clear reason.
+7. Make the quality-first complete change that satisfies the goal after the
+   affected boundary is understood.
+8. After the change, re-check every affected area.
+9. Run relevant checks, tests, builds, or manual verification when available.
+10. Fix errors or regressions caused by the change before calling the work
+    complete.
+
+Function and program structure:
+
+- Prefer simple, direct structure with locally understandable control flow and
+  only the moving parts justified by the verified boundary.
+- Use existing source-of-truth modules and established infrastructure when they
+  already own the boundary.
+- Add a helper or abstraction only when it names a real shared concept,
+  preserves an invariant, or removes meaningful repetition.
+- Avoid premature class hierarchies, generic frameworks, new registries, plugin
+  layers, event buses, background schedulers, callback/subscription systems, or
+  other coordination machinery unless the current verified requirement needs
+  them, including failure paths, lifecycle cleanup, and observability.
+- Simple never means hardcoded, temporary, case-specific, or test-only code.
+
+## Review Discipline
+
+The goal of review is defect discovery, not praise or consensus. Do not defend
+an implementation; verify whether code, docs, tests, and product boundaries
+actually agree.
+
+- Report findings only, in priority order.
+- Each finding cites a file and line as evidence.
+- Mark speculation as speculation when the claim is not directly confirmed by
+  code, tests, or pinned SDK source.
+- Do not defer with "can be done later." If a defect can be fixed safely now
+  within the current affected boundary, classify it as fix-now.
+- Do not rely on existing tests passing as proof of correctness.
+- When a defect is found, expand the search to callers, callees, and adjacent
+  boundaries. Trace upstream until the shared rule, type, or invariant the
+  defect violates is identified.
+
+### Reduction Detection
+
+When a change is framed as refactor, cleanup, alignment, simplification, or
+documentation synchronization, check whether supported behavior, tool authority,
+or a user-facing claim became smaller.
+
+Inspect git history when tool names, response fields, status values, runtime
+guidance, public docs, tests, golden scenarios, or supported-claim lists are
+removed, renamed, or narrowed.
+
+If history shows prior behavior, classify the current work as restoration,
+replacement, or intentional removal before reviewing it as new functionality. Do
+not accept "new feature" framing until the prior behavior has been accounted
+for. If a removal is intentional, cite the user decision, issue, commit, or
+source evidence that changed the requirement.
+
+A passing test is not proof that the tested behavior is intended. For tests that
+prevent unsafe or unsupported behavior, read the test body and state what it
+prevents from returning before treating it as stale or necessary.
+
+Documentation and tests can narrow together, so agreement between them is not
+enough. Compare code, tests, docs, runtime outputs, and history across the same
+boundary.
+
+For `userAnswerUse` and golden-document tests, verify semantic polarity instead
+of string presence alone. A test that reads a document fixture must distinguish
+allowed-answer text from forbidden, diagnostic, or exclusion text, and it must
+fail when required section markers are missing.
+
+When findings reveal structural problems, describe how the feature would be
+designed from scratch with no legacy constraints. Start from type dependencies
+and explicit separation of boundaries and responsibilities.
+
+## Implementation Integrity
+
+- Do not hardcode values to bypass real validation, live integration, registry
+  policy, or mainnet checks.
+- Do not add temporary branches solely to satisfy one failing case.
+- Do not manipulate tests, fixtures, generated files, snapshots, package
+  metadata, or source files just to make checks pass.
+- Test doubles, fixtures, placeholders, and config constants are allowed only
+  when their scope is explicit and they are not presented as product
+  functionality.
+- Do not fake liquidity, quotes, transactions, wallet state, package IDs, or
+  mainnet support.
+- If technical debt remains, name it explicitly and explain why it is not being
+  removed now.
+- Prefer removing avoidable debt in the same change when it is safe and within
+  the affected boundary.
+
+## Numeric, Financial, And Protocol Honesty
+
+Numeric and unit safety:
+
+- Treat raw token amounts, display amounts, decimals, slippage, bps, quote
+  quantities, min-out values, gas, and balance deltas as safety-critical data.
+- Do not infer token decimals from token symbols, memory, UI convention, or
+  common ecosystem defaults. Use a verified source of truth such as pinned SDK
+  metadata or verified mainnet onchain metadata.
+- Keep raw amounts as integer strings or `BigInt` values. Do not use floating
+  point `number` arithmetic for token balances or signable quantities.
+- Keep display amounts presentation-only and label them as display data. Do not
+  feed display strings back into signing, quoting, or review-time simulation
+  without an explicit raw conversion step.
+- Formatting may strip trailing fractional zeros for readability, but it must
+  not use exponent notation or silently round away raw precision.
+
+Financial and protocol honesty:
+
+- Treat every balance, quote, fee, rebate, stake, locked amount, price, route
+  quantity, and derived value as financial information. It must have a clear
+  source, unit, precision boundary, and product meaning.
+- Derived numbers must be honest about how they were produced. Do not hide
+  rounding, precision loss, simulation assumptions, registry lookups,
+  display-only conversion, cache age, or unavailable raw amounts.
+- Separate raw integers, display amounts, simulated values, indicative quotes,
+  cached registry metadata, and live onchain state in types, docs, and
+  user-facing explanations.
+- Use protocol terms as the protocol defines them. For DeepBook and future DeFi
+  integrations, prefer the pinned SDK source, official protocol documentation,
+  verified smart contract source, or mainnet onchain evidence over invented
+  wording.
+- Do not rename, reinterpret, or simplify protocol concepts in a way that
+  changes their meaning.
+- If a protocol, SDK, or contract source does not define a term, quantity,
+  status, or behavior clearly enough, mark it as unsupported, unavailable, or
+  requiring verification. Do not fill the gap with imagination or confident
+  prose.
+
+## Stateful/API Change Protocol
+
+For session, review, signing, MCP tool, HTTP endpoint, wallet, adapter, or other
+stateful/API changes, do not start from the patch. Use this order:
+
+1. Define the boundary being changed.
+2. Write or inspect the relevant state and input combination table.
+3. Decide the canonical source of truth.
+4. Check response consistency across HTTP, MCP, store, browser, wallet, adapter,
+   and docs as applicable.
+5. Add or update tests for failure combinations.
+6. Make the change.
+7. Search for the same pattern with `rg` and inspect adjacent paths.
+8. Run the relevant full verification before calling the work complete.
+
+For non-trivial changes, record the matrix in `.WORK/` notes, the task report,
+or tests. Do not rely on unstated intent.
+
+Avoid case-driven exception stacking. When a bug appears as a specific case,
+first ask which general boundary rule it violates. Fix the shared rule, mapper,
+type, or invariant when possible instead of adding a case-specific branch for
+that one case.
+
+Required invariants:
+
+- Store methods own state transitions. HTTP and MCP layers should map store
+  results and errors, not reimplement transition rules.
+- Public status fields must be derived through shared mapping code. Do not
+  hand-map equivalent status concepts separately in HTTP and MCP.
+- Idempotency checks must compare all identity fields needed for correctness,
+  such as `reviewSessionId`, `planId`, status, and `txDigest`.
+- A successful state-changing response must reflect the state actually stored
+  after the operation.
+- Do not leak session or domain details before token validation. After token
+  validation succeeds, lifecycle and domain errors should be specific unless a
+  different security decision is documented in code or tests.
+
+Failure combinations are boundary-specific. For session/review work, include
+wrong token, missing session, wrong `planId`, expired session, finalized session,
+duplicate request, conflicting duplicate request, and mismatched action data. For
+other boundaries, define the equivalent negative combinations before editing.
+
+## Product Rules
+
+- Treat AI reasoning and transaction authorization as separate concerns.
+- Treat natural-language intent evidence and transaction construction as
+  separate concerns.
+- Do not pass executable transaction bytes from the MCP layer as trusted signing
+  material.
+- The review layer must regenerate and verify signable actions before wallet
+  signing.
+- The review layer exists to explain execution before authorization, not to
+  guarantee safety.
+- Review checks must use deterministic checks, not opaque AI risk scores.
+- Use `Ready for your review`, `Review needs updating`, and `Review blocked` for review
+  display states. These labels describe review information, not permission to
+  request wallet approval or a guarantee of execution. Keep public state enums
+  unchanged when editing display labels. Avoid language that implies absolute safety.
+- Keep unsupported actions clearly unsupported. Do not add unimplemented intent
+  types in code.
+- Prefer read-only utilities before write actions when adding protocol coverage.
+- Intent evidence reports are useful product outputs by themselves. Do not treat
+  transaction creation or signing as required for a feature to have value.
+- Do not ask users to speak in contract, function, coin type, or raw amount
+  terms when a supported natural-language settlement asset group can be resolved
+  from pinned SDK registry evidence.
+- Do not silently choose USDC, USDT, or another settlement token for a
+  USD-denominated user intent. Expose the supported settlement asset group
+  evidence and required user choices.
+- USD-denominated evidence checks require a runtime-facing preflight contract.
+  AI-client guidance exposed through MCP instructions, resources, prompts, and
+  tests must require `read.get_server_status` before USD-denominated coverage,
+  balance-total, or shortfall answers.
+- Ordinary MCP tools are evidence and card gateways. They may create review
+  sessions and return internal cards, but model calls must not authorize
+  signing or execution. Scoped app-only actions admit an exact user selection;
+  the backend performs wallet I/O and verifies each resulting signature.
+- The local settings control panel is a review-server frontend mutator. MCP may
+  create a settings session URL and read current settings, but settings
+  mutations must happen through the local settings page after Host/Origin checks
+  and settings-token validation.
+
+## Network Policy
+
+Product specs, public docs, UX copy, product-facing AI/tool responses,
+registries, and signable actions are mainnet-only.
+
+Allowed as product functionality:
+
+- mainnet packages;
+- mainnet token types;
+- mainnet pools or markets;
+- mainnet execution data.
+
+Not allowed as product functionality:
+
+- testnet-only actions;
+- planned-mainnet actions;
+- faucet-only assets;
+- fake liquidity;
+- demo-only flows.
+
+Internal experiments may use testnet, but they must not appear in product docs,
+registries, UX copy, product-facing AI/tool responses, or supported-action
+lists. Agents may discuss testnet or WIP surfaces only as unsupported internal
+context or direct analysis, never as available product functionality.
+
+Do not silently substitute mainnet assets, pools, package IDs, or protocol
+objects. Resolved assets, pools, packages, and functions must be shown
+explicitly in the review layer.
+
+Mainnet guards must verify both declared network configuration and the actual
+connected chain identifier. Do not rely on a string literal such as
+`network: "mainnet"` alone.
+
+## Registry And Generated Files
+
+- Markdown files are explanatory references for AI and humans.
+- JSON registries are local policy, allowlists, aliases, and known metadata.
+- Prefer official SDKs, official RPC endpoints, official deployment registries,
+  or direct mainnet onchain inspection for live state.
+- Do not treat local JSON as live liquidity, live balances, live quotes, or
+  final execution truth.
+- Generated registry files should include generation source, network, timestamp,
+  and generator script when practical.
+- Do not hand-edit generated files unless they are explicitly marked as manual.
+- If generated registry data changes, update related docs or state why no doc
+  change is needed.
+
+## SDK And CLI Source Of Truth
+
+Code must use the pinned SDK and verified mainnet sources before introducing
+local logic:
+
+- DeepBook mainnet asset and pool metadata comes from `@mysten/deepbook-v3`
+  `mainnetCoins` and `mainnetPools`.
+- Display-to-raw conversions use pinned Sui SDK utilities such as `parseToUnits`
+  and `parseToMist` when applicable.
+- Wallet coin balances come from Sui SDK `client.core.listBalances`.
+- DeepBook quote evidence comes from the pinned DeepBook SDK quote path or the
+  existing SDK-backed simulation adapter.
+- Do not reimplement SDK registries, parsers, quote APIs, or protocol math under
+  local helper names when the pinned SDK already owns that source of truth.
+- Sui CLI can be used only as read-only/debug verification evidence through
+  reviewed allowlisted utilities. It is not runtime authority,
+  transaction-building input, signing material, signing readiness, or wallet
+  authorization evidence.
+
+## Review State Model
+
+Keep account-independent planning separate from account-bound review.
+
+- `ActionPlan`: proposal created before wallet connection.
+- `ReviewState`: wallet/account-bound verification result.
+- Adapters that need original user intent captured for local activity analysis
+  should put the sanitized intent object at `ActionPlan.adapterData.requestedIntent`.
+- Adapter data and review evidence must never include session tokens, token
+  hashes, URL fragment tokens, private keys, transaction bytes, signatures,
+  seeds, or mnemonics.
+- Do not put wallet-specific checks such as balances, gas result, transaction
+  simulation result, or before/after balances into account-independent plans.
+- Do not assume wallet balances, gas availability, or coin selection before
+  wallet connection.
+- Recompute account-bound checks after wallet connection in the review layer.
+- Use full transaction simulation for review-time effects, gas, object changes,
+  and balance changes.
+- For Sui SDK v2 code, review-time simulation uses the public Sui gRPC
+  `transactionExecutionService.simulateTransaction` with `checks: ENABLED`
+  and `doGasSelection: true`. Send the stored transaction BCS and require
+  identical returned BCS and an effects digest matching the stored material.
+  Mock-gas simulation and rewritten transactions are not review evidence.
+- Treat dev-inspection/debug simulation as separate from review-time transaction
+  simulation; do not present debug inspection as signing readiness.
+
+## Session Store Rule
+
+For the current implementation, the MCP layer and review layer must share the
+same authoritative session store.
+
+The shared runtime uses SQLite as the authoritative source for card and live
+session state. Store methods commit admission, revision changes and results;
+MCP, HTTP and View consumers do not keep independent copies of that state.
+In-memory fixtures may model external dependencies in tests, but do not prove
+SQLite admission, rollback or restart guarantees. Frame recreation and chat
+navigation are not state transitions.
+
+Execution results belong to an exact `reviewSessionId` and `attemptId`. A
+review explicitly references its current attempt, and earlier attempts remain
+readable history. Do not use ambiguous global "latest result" semantics.
+
+Card permissions are short-lived, scoped to the card and target, and carried
+only in host UI metadata. Reads never create approval, pairing or a signature
+request. Frame recreation is not an input transition. Its state read may
+reconcile existing deadlines and wallet records without starting a new
+operation. Only the backend owns admission, request deadlines and chain
+observation. Settings page tokens remain in URL fragments and authenticated HTTP headers, never query strings or logs.
+
+## Utility Script Rule
+
+- Utility scripts should expose concrete reusable state inspection or reporting
+  functionality.
+- Keep utility scripts separate from the core review and signing flow.
+- Avoid hidden side effects.
+- Document inputs, outputs, and assumptions in `docs/UTILITY_INDEX.md`.
+- Prefer read-only utility scripts unless a write action is explicitly required.
+- Sui CLI based utilities must allowlist concrete read or debug commands, record
+  the observed `sui --version`, and reject arbitrary shell commands, arbitrary
+  Move calls, package calls, key handling, signing, execution, or config
+  mutation unless a separate reviewed plan explicitly owns that write boundary.
+- Treat Sui CLI replay, trace, and gas-profile output as development/debug
+  evidence. Do not present it as review-time simulation, transaction-building
+  input, signing material, signing readiness, or wallet authorization evidence.
+
+## MCP Tool Safety
+
+- Tool names, descriptions, and schemas must be concise, literal, and
+  instruction-free.
+- Use MCP-compatible tool names. Prefer dot prefixes such as
+  `read.list_deepbook_pools` over slash names.
+- Do not include hidden instructions, prompt-like text, policy text, or
+  model-behavior requests in tool descriptions.
+- Do not expose arbitrary shell execution, arbitrary Move calls, arbitrary
+  package calls, or private-key handling.
+- Prefer purpose-specific tools with explicit schemas over broad free-form
+  tools.
+- Validate tool inputs and outputs at the MCP server boundary.
+- Review whether tool authority expanded whenever a tool schema or description
+  changes.
+- Settings tools are session-gateway tools. They may create a local settings
+  page session or read current settings. They must not mutate settings directly,
+  execute transactions, sign, create custody, or produce signing material.
+- For stdio MCP servers, stdout is reserved for valid MCP JSON-RPC messages.
+  Send logs to stderr or a file. Do not use `console.log` in stdio server code.
+- Successful MCP tool output should use `structuredContent` plus a text JSON
+  fallback when the SDK supports structured output. MCP error responses use
+  `isError: true` with a text JSON fallback because the pinned SDK skips
+  output-schema validation for error results.
+
+## MCP API Response Clarity
+
+Design and review MCP API responses as standalone evidence.
+
+Assume a connected AI client, coding agent, reviewer, or human operator may see
+one tool response without reading the rest of the repository, prior chat, or
+another tool response.
+
+Every public MCP response shape should make these points clear from that
+response alone:
+
+- what question or operation this response can support;
+- what source produced the facts, including network, SDK, transport, snapshot
+  time, and unit source when relevant;
+- which returned fields may be used in a user-facing answer;
+- which returned fields are diagnostic, price-only, display-only, or otherwise
+  not answer amounts;
+- which claims are unsupported by this response;
+- whether any required user choice is still missing;
+- whether a follow-up tool is required, and exactly which tool and field should
+  be used.
+
+Keep API responsibilities isolated.
+
+A field in one tool response must not require hidden knowledge of another tool
+to understand its own meaning.
+
+Cross-tool references are allowed only as explicit follow-up guidance, for
+example: this quote result is a price estimate only; for payment amount or
+shortfall answers, call `read.preview_intent_evidence` and use
+`responseSummary`.
+
+Do not make a different API response necessary just to understand whether the
+current response is safe to use for a conclusion. If a response cannot support a
+conclusion, say that in the response itself with a plain field name and a plain
+reason.
+
+For API implementation work:
+
+- inspect every status branch, success branch, error branch, and optional field
+  in the affected response;
+- prefer a small response-local summary or use-guidance object over scattered
+  negative flags when the result is meant to guide AI answers;
+- keep raw facts, display amounts, price estimates, wallet-balance amounts,
+  transaction facts, and execution/session state in separate fields;
+- use ordinary field names such as `amountsUsedForAnswer`,
+  `separateQuoteOutputs`, `canUseForPaymentAnswer`, or
+  `requiredPaymentAnswerField` when those names describe the behavior directly;
+- avoid field names whose meaning depends on product memory, such as unexplained
+  `contract`, `coverage`, `gate`, `readiness`, `evidence`, or `support` wording.
+
+For API review work, block or fix the change when:
+
+- the response can be misunderstood after being copied without surrounding
+  documentation;
+- the response mixes price estimates, wallet balances, transaction facts, or
+  execution state into one conclusion without naming which fields are used;
+- the response tells an AI client not to use a value but does not identify the
+  field that should be used instead;
+- the response points to another tool without explaining what the current tool
+  result does and does not mean by itself;
+- the response requires prior chat, hidden product vocabulary, or a separate
+  document to avoid an unsafe user-facing answer.
+
+## Review Server Safety
+
+- Bind the local review server to `127.0.0.1`.
+- Use a dynamic port unless a fixed port is explicitly required.
+- Implement Host and Origin checks in the review server itself.
+- Do not treat Host or Origin checks as authentication. Settings APIs must validate their session token; internal app actions
+  must validate their scoped UI permission and stored target/revision.
+- Do not use MCP SDK host validation helpers as a substitute for review server
+  authentication.
+
+## Dependency Policy
+
+- Pin Sui, DeepBook, MCP, and wallet-related dependencies to explicit versions
+  during active development.
+- Commit the lockfile.
+- Do not upgrade SDKs casually.
+- When changing the published package or MCP server release version, update all
+  release metadata in the same change: `package.json`, root/package entries in
+  `package-lock.json`, and `server.json` top-level and package versions.
+- Before completing a release-version change, search committed repository
+  surfaces excluding `node_modules/`, `dist/`, `.git/`, and `.WORK/` for the old
+  release version and classify any remaining matches as dependency versions,
+  fixture data, or stale release metadata.
+- When changing an SDK or wallet-related dependency version, update pinned
+  version documentation such as `docs/SDK_API.md` when that dependency is listed
+  there.
+- If an SDK is upgraded, re-run adapter, review, signing, and
+  registry-generation checks.
+
+## Completion Criteria
+
+Work is complete only when:
+
+- the requested change is implemented;
+- the affected boundary still looks robust when reviewed again from product
+  purpose, code paths, user flows, tests, and documentation;
+- affected code, docs, interfaces, and user flows have been reviewed after the
+  change;
+- relevant checks, tests, builds, or manual verification have been run when
+  available;
+- errors introduced by the change have been fixed;
+- remaining limitations are explicitly documented;
+- for non-trivial work, the final review compares the completed work against the
+  specification baseline;
+- every baseline requirement is implemented and verified, or named directly as a
+  missing planned requirement;
+- passing tests, reduced scope, or internal consistency of a smaller
+  implementation does not replace baseline comparison;
+- final repository status is checked, including untracked files;
+- unexpected files are classified or cleaned up before final response;
+- if previous progress was overstated, the final response corrects the record.
+
+## Quality direction
+
+Quality work continues along three areas; progress in all three matters, and
+work that advances more than one at once is preferred over work that advances
+only one in isolation:
+
+- Intent, evidence, and answer quality: understand the request, route it to the
+  right tool (prompt surfaces, `userAnswerUse` response guidance), and answer
+  only from verified mainnet evidence, including saying plainly when a question
+  cannot be answered from the returned evidence.
+- Protocol breadth: additional protocol adapters registered through the
+  descriptor contract; protocol names appear in public docs only after a
+  concrete support decision. When several protocols support an action, the bare
+  action prompt asks the user to choose instead of routing silently.
+- Execution-trust foundation: what the user reviewed is exactly what gets
+  signed, under any wallet and any signing speed — the review-session state
+  machine, atomic per-review-revision admission, verified sign-only wallet
+  responses, bounded local waits with late-callback guards, scoped UI permission, runtime lifecycle
+  stability, and packaging and runtime operability.