[VPD-893]: Add DeviationBoundedOracle Contracts

.claude/rules/solidity-style.md

@@ -0,0 +1,145 @@
+---
+description: Solidity coding standards for all contract and interface files
+globs: contracts/**/*.sol
+---
+
+# Solidity Style Rules
+
+## Contract Layout (top -> bottom)
+
+1. Constants (`public constant`)
+2. Immutables (`public immutable` or `internal immutable`)
+3. State variables (`public` for auto-getters where possible; `internal` for structs -- see Function Visibility)
+4. Events
+5. Errors (custom errors only -- **no `require` with strings**)
+6. Modifiers
+7. Constructor / `initialize`
+8. `receive` / `fallback`
+9. Functions (ordered by visibility, see below)
+
+---
+
+## Function Ordering
+
+Within the functions section, order by visibility:
+
+`external` -> `public` -> `internal` -> `private`
+
+Within each visibility group:
+
+1. ACM / access-gated (e.g. `onlyOwner`, `_checkAccessAllowed`) first
+2. Permissionless second
+
+Within each access level:
+
+1. State-changing
+2. `view`
+3. `pure`
+
+---
+
+## Function Visibility
+
+- **No `public` functions** -- Use `internal` helper + `external` wrapper instead.
+  - **Exception:** Inherited/overridden functions from OZ or other base contracts (e.g. `getPrice()`, `initialize()`).
+- State variables **should** be `public` (auto-getter). Define the corresponding getter signature in the interface.
+  - **Exception:** Struct state variables -- Solidity `public` structs generate flattened return values (one value per field), not a full struct return. Use `internal` storage + explicit `external` getter that returns the struct from `memory`.
+  - **Exception:** Array state variables -- Solidity `public` array auto-getters only allow index-based access. Keep the array `public` (index-based access via auto-getter), but also add an explicit `external` getter that returns the full array.
+
+---
+
+## Constants & Immutables
+
+- Constants in contracts **must** be `public constant` (auto-getter).
+- Constants in `library` contracts **must** be `internal constant` (Solidity restriction -- libraries cannot have `public` state).
+- Contract addresses that will never change (e.g. Venus, OZ dependencies) **must** be `immutable` or `constant` -- never stored in regular state variables.
+- Upgradeable contracts **may** have a `constructor` but **only** to set `immutable` variables. All other initialisation goes in `initialize()`.
+
+---
+
+## NatSpec
+
+**Comment style:**
+
+- **Multiline** NatSpec (2+ tags or long descriptions) -> use `/** ... */` block comments.
+- **Single-line** NatSpec (one short tag) -> use `///` inline comments.
+
+**Required on all `external` and `public` functions** and their interface declarations:
+
+- `@notice` -- what the function does
+- `@param` -- each parameter
+- `@return` -- each return value
+- `@custom:error` -- each custom error the function can revert with
+- `@custom:event` -- each event the function can emit
+
+**Required on all `internal` functions:**
+
+- `@notice` -- what the function does (brief is fine)
+- `@param` -- each parameter
+- `@return` -- each return value
+- `@custom:error` -- each custom error the function can revert with (integrators of the calling `external` function inherit these)
+
+**Error attribution rule:**
+
+- `external`/`public` functions document **only** errors thrown directly in their own body.
+- Errors originating from `internal` helpers are documented on those `internal` functions instead.
+- **Interface declarations** may include the full list of possible errors (direct + internal) for integrator convenience. Only include errors added by the feature contract -- no need to document errors from imported OZ or ACM base contracts.
+
+---
+
+## Caching
+
+- **Cache everything** -- Never SLOAD or external-call the same value twice. Cache in local variables.
+- Copy storage structs to `memory` at function entry when reading multiple fields.
+- Cache `msg.sender`, `block.timestamp`, array lengths, and repeated mapping lookups.
+
+---
+
+## Errors & Events Placement
+
+- **Custom errors only** -- never `require(condition, "string")`.
+- For contracts **around ~500 lines or fewer**: define errors and events in the contract itself.
+- For contracts **over ~600 lines**: move **all** errors and events (existing ones included) to the interface -- not just new ones. This keeps the contract focused on logic only.
+- Prefix errors with the contract/interface name context (e.g. `OracleNotEnabled`, `InvalidBoundRatio`).
+
+---
+
+## Security
+
+- **CEI pattern** -- Always follow Checks-Effects-Interactions order. Update all state before making any external calls.
+- **SafeERC20** -- Always use `SafeERC20` for token transfers. For approvals always use `forceApprove` (never raw `.approve()`).
+- **Zero address validation** -- Always validate against `address(0)` for all address parameters in constructors and `initialize()`.
+
+---
+
+## Events
+
+- Setter functions **must** emit events logging both the old and new value.
+- If the old value is only needed for the event (not for any logic), emit **before** writing storage to avoid an unnecessary cache variable. This is safe for ACM-guarded setters since they are access-controlled and carry no re-entrancy risk:
+  ```solidity
+  // preferred -- emit before write, no cache needed
+  emit ValueUpdated(storedValue, newValue);
+  storedValue = newValue;
+  ```
+- If the old value is also needed for logic, cache it first:
+  ```solidity
+  // cache when old value is used in logic too
+  uint256 oldValue = storedValue;
+  storedValue = newValue;
+  emit ValueUpdated(oldValue, newValue);
+  ```
+
+---
+
+## General Style
+
+- **DRY** -- If the same logic is used in multiple places, extract it into a shared `internal` function and call it from all the relevant `external` functions. Never duplicate logic.
+- Use named return variables only when it improves readability; otherwise use explicit `return`.
+- Use `uint256` over `uint` -- always explicit bit width.
+- Avoid magic numbers -- define named constants.
+- One contract per file; filename matches contract name.
+- Upgradeable contracts **must** declare a storage gap as the last state variable. The gap size should be `50` minus the number of storage slots already declared in that contract, so the total always sums to 50:
+  ```solidity
+  // e.g. contract declares 3 storage variables -> gap = 47
+  uint256[47] private __gap;
+  ```

.claude/rules/testing.md

@@ -0,0 +1,36 @@
+---
+description: Rules for when and how to write or update tests
+globs: test/**/*.ts
+---
+
+# Testing Rules
+
+## When to Write Tests
+
+- During **feature implementation**, tests are written only on explicit request -- do not auto-generate tests while building contracts.
+- Once implementation is complete (e.g. during fixes, reviews, or audits), tests are expected and should be written when asked.
+- Once tests exist and code changes are made later: make the code change first, then immediately ask the user if you should update the tests before touching them. _(Also in CLAUDE.md so this rule is always in context.)_
+- Write tests against **intended behaviour**, not against what the code currently does. If a test fails, ask the user whether the behaviour is correct or the code has a bug -- never silently adjust a test to make it pass.
+
+---
+
+## Assertions
+
+- **Always exact** -- `expect(actual).to.equal(expected)`. Weak assertions like `expect(balance).to.be.gt(0)` when the expected value is known are not acceptable.
+- Use `gt` / `lt` only when the result is genuinely variable (e.g. a loss scenario). Even then, compute the expected value and assert it exactly or near-exactly.
+- `closeTo` / approximate assertions only when rounding genuinely prevents an exact comparison -- never as a shortcut.
+
+---
+
+## Events
+
+- Always assert the primary function-specific event -- not just underlying `Transfer` / `Approval`.
+- Use `.to.emit(contract, "EventName").withArgs(...)` with all arguments verified.
+
+---
+
+## Mocking
+
+- Prefer the real code path. Only mock external dependencies (oracles, external protocols) when there is no alternative.
+- Use `@defi-wonderland/smock` for mocking external contracts. Prefer `smock.mock` — use `smock.fake` only when `smock.mock` cannot be used (e.g. the contract has no deployable artifact).
+- Never mock internal contract behaviour -- test it directly.

.claude/skills/feature/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: feature
+description: Start or resume feature development workflow -- restores context, creates feature doc, creates task plan, implements contracts, updates feature docs
+argument-hint: <feature-name>
+---
+
+# Feature Development Workflow
+
+Working on feature: **$ARGUMENTS**
+
+## Execution Order
+
+1. **Read research** -- Read all files in `research/$ARGUMENTS/` if they exist
+2. **Create feature doc** -- Write `feature-docs/$ARGUMENTS.md` by synthesising the research docs (see below)
+3. **Create task plan** -- Write `.task_plan.md` -- primarily informed by the feature doc; may also reference research docs directly for additional detail
+4. **Implement** -- Write contracts and interfaces following Solidity style rules (see `.claude/rules/solidity-style.md`)
+5. **Update feature doc** -- Ongoing throughout implementation: log progress, decisions made, and any design changes
+6. **Tests** -- Only when explicitly asked
+
+If `feature-docs/$ARGUMENTS.md` already exists, read it first to restore context, then continue from where work left off.
+
+---
+
+## Feature Doc (`feature-docs/$ARGUMENTS.md`)
+
+The feature doc is the **single source of truth** for the feature. Create it before the task plan by synthesising the research docs. Keep it short and concise — capture only what is essential, not a full rewrite of the research.
+
+It should capture:
+
+- **What needs to be done** -- scope and goal of the feature
+- **Where to make changes** -- which contracts, interfaces, and files are involved
+- **How to make changes** -- implementation approach; if the research doc prescribes a specific approach follow it, otherwise use a subagent to analyse the codebase and determine the best approach before writing this section
+- **Key design decisions** and **why** they were made
+- **Trade-offs and gotchas** -- anything worth watching out for
+
+During implementation, keep this doc updated with actual progress and any decisions that deviate from the original plan. All design decisions go here — if something changes, update this doc. Research docs are input only: used once to create the initial feature doc and never updated after that.
+
+---
+
+## Task Planning (`.task_plan.md`)
+
+Always create `.task_plan.md` at the project root before starting implementation. This file:
+
+- Contains the execution plan with phases and checklist
+- Tracks progress, errors, and current status
+- Is **not tracked by git** -- purely a working file
+- Persists across sessions for the same feature -- append, don't overwrite
+
+---
+
+## Research (`research/`)
+
+Research docs in `research/$ARGUMENTS/` feed the initial feature doc and are not touched after that. They can be generated by Claude during a research phase or pasted in directly by the user. They may contain:
+
+- **Design docs** -- architecture, interface design, flow diagrams
+- **Implementation docs** -- step-by-step implementation details
+- **Reference material** -- relevant protocol docs, external references
+- **Analysis** -- security considerations, gas analysis, comparisons
+
+**Important**: Research docs (especially implementation docs) may contain code snippets -- treat these as pseudo-code for inspiration only, NOT as source of truth. Always write correct, bug-free logic yourself. If you see a better approach than what is described, always present it to the user -- explain what it is and why it is better -- and ask whether to use it instead.
+
+---
+
+## File Structure
+
+New oracle contracts follow this layout:
+
+```
+contracts/
+  ├── interfaces/IMyOracle.sol     # Interface first
+  └── oracles/MyOracle.sol         # Implementation
+
+test/
+  └── MyOracle.ts                  # Unit tests (only when asked)
+
+deploy/
+  └── NN-deploy-my-oracle.ts       # Hardhat-deploy script
+
+feature-docs/
+  └── $ARGUMENTS.md                # Feature doc (git-tracked)
+
+research/
+  └── $ARGUMENTS/                  # Research input (NOT git-tracked)
+```
+
+---
+
+## Subagent Strategy
+
+During active development, if asked something mid-work (explain code, find usages, compare approaches), use a subagent to handle it. This keeps the main context window clean — delegate the exploration, return only the answer.
+
+---
+
+## Operational Rules
+
+1. **Ask freely** -- If anything is unclear or ambiguous, ask the user before proceeding. Never assume.
+2. **Read before decide** -- Before major decisions, re-read the feature doc and plan file.
+3. **No landmines** -- Find root causes, no temporary fixes. Leave no hidden hazards in the code.
+4. **2-Action Rule** -- After every 2 search/browse operations, IMMEDIATELY save key findings to files.
+5. **Update after act** -- After completing any phase: mark status, log errors, note files modified.
+6. **Log ALL errors** -- Every error goes in the plan file.
+7. **Never repeat failures** -- `if action_failed: next_action != same_action`. Track attempts, mutate approach.
+8. **3-Strike Protocol** -- After 3 failed attempts at the same problem, escalate to user.