Strengthen CI, add issue templates, and improve documentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- Foundry version (`forge --version`):
+- Solidity version:
+- OS:
+- Network (if applicable):
+
+## Additional Context
+
+Any other context, screenshots, or log output.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature Request / Task
+about: Propose a new feature or describe a task from a spec
+title: "[FEAT] "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+Brief description of the feature or task.
+
+## Motivation
+
+Why is this needed? Link to the relevant spec or discussion if applicable.
+
+## Specification
+
+### Requirements
+
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Design Considerations
+
+Describe any architectural decisions, trade-offs, or security considerations.
+
+## Dependencies
+
+List any external dependencies, upstream changes, or blocking tasks.

.github/workflows/claude.yml

@@ -0,0 +1,129 @@
+name: Claude Code Assistant (Solidity)
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  issues:
+    types: [opened, assigned]
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  # ─── 1. Claude Code Assistant (triggered by @claude mentions) ─────────────
+  claude-assistant:
+    name: Claude Code
+    runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 1
+
+      # Make Foundry & Solhint available to Claude so it can run them
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install Solhint
+        run: npm install -g solhint
+
+      - name: Run Claude Code
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: |
+            --max-turns 15
+            --allowedTools "Bash(forge build),Bash(forge test*),Bash(forge fmt*),Bash(forge coverage*),Bash(forge snapshot*),Bash(solhint*),Read,Edit,Write,Glob,Grep"
+            --system-prompt "You are an expert Solidity and EVM smart contract engineer.
+
+            CONTEXT:
+            - This repo uses Foundry (forge, cast, anvil). Tests are in test/, contracts in src/, scripts in script/.
+            - Dependencies are managed as git submodules in lib/.
+            - Always check forge build and forge test pass before suggesting changes.
+            - Solidity version: check foundry.toml or pragma statements before assuming.
+
+            SECURITY RULES (non-negotiable):
+            - Never suggest patterns that bypass checks-effects-interactions.
+            - Flag any reentrancy, integer overflow, access control, or oracle manipulation risks.
+            - Prefer OpenZeppelin battle-tested libraries over custom implementations.
+            - Never suggest storing private keys or secrets in contract state or scripts.
+            - When reviewing upgradeable contracts, always check storage layout collisions.
+
+            CODE QUALITY:
+            - Write Solidity tests (not just JS/TS) using forge-std.
+            - Include fuzz tests (vm.assume, bound()) for numeric inputs.
+            - Add NatSpec comments (@notice, @param, @return) on all public functions.
+            - Report gas impact of suggested changes using forge snapshot.
+            - Follow the Checks-Effects-Interactions pattern strictly.
+
+            GAS OPTIMISATION:
+            - Suggest packing storage slots where safe to do so.
+            - Prefer custom errors over revert strings.
+            - Use immutable and constant where appropriate.
+            - Flag unnecessary SLOADs in loops."
+
+  # ─── 3. Automated security review on every PR ─────────────────────────────
+  claude-security-review:
+    name: Claude Security Review
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' && github.event.action == 'opened'
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 2
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Automated Claude Security Review
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+            BRANCH: ${{ github.head_ref }}
+
+            Perform a focused Solidity security and gas review of the changes in this PR.
+            Use `git diff HEAD~1` to see what changed.
+
+            Structure your review as:
+
+            ## 🔴 Critical / High (block merge)
+            Reentrancy, access control bypasses, integer issues, fund loss vectors.
+
+            ## 🟡 Medium (should fix)
+            Logic bugs, incorrect event emissions, missing input validation.
+
+            ## 🟢 Low / Informational
+            Gas optimisations, NatSpec gaps, style issues.
+
+            ## ✅ Gas Report Delta
+            Run `forge snapshot --diff` if applicable and summarise changes.
+
+            If there are no issues in a category, write "None found."
+            Be concise and actionable. Cite the file and line number for each finding.
+          claude_args: |
+            --max-turns 10
+            --allowedTools "Bash(forge build),Bash(forge test*),Bash(forge snapshot*),Bash(git diff*),Read,Glob,Grep"

.github/workflows/slither.yaml

@@ -0,0 +1,30 @@
+name: Slither Analysis
+
+on:
+  pull_request:
+    branches: [main, master, staging, dev, "feat/**", "fix/**"]
+
+jobs:
+  analyze:
+    name: Slither
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Run Slither
+        uses: crytic/slither-action@v0.4.0
+        id: slither
+        with:
+          fail-on: none
+          sarif: results.sarif
+          slither-config: slither.config.json
+
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif

.github/workflows/test.yaml

@@ -1,36 +1,59 @@
 name: test
 
+permissions:
+  contents: read
+
 on:
   pull_request:
-    branches: [main, master, staging, dev, feat/**, fix/**]
+    branches: [main, master, staging, dev, "feat/**", "fix/**"]
 
 env:
   FOUNDRY_PROFILE: ci
 
 jobs:
-  check:
-    strategy:
-      fail-fast: true
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Show Forge version
+        run: forge --version
+
+      - name: Build and check contract sizes
+        run: forge build --sizes
 
-    name: Foundry project
+  test:
+    name: Test
     runs-on: ubuntu-latest
+    needs: build
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
 
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Run tests
+        run: forge test -vvv
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
         with:
-          version: nightly
-
-      - name: Run Forge build
-        run: |
-          forge --version
-          forge build --sizes
-        id: build
-
-      - name: Run Forge tests
-        run: |
-          forge test -vvv
-        id: test
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Generate coverage report
+        run: forge coverage