Junirezz · Junirezz · Jun 27, 2026 · Jun 26, 2026
diff --git a/docs/CROSS_REPO_INTEGRATION_TESTS.md b/docs/CROSS_REPO_INTEGRATION_TESTS.md
@@ -0,0 +1,29 @@
+# Cross-Repo Integration Test Ownership and Coordination Model
+
+This document defines the ownership, coordination, and workflow for integration tests that span multiple repositories and services within the YieldVault-RWA ecosystem.
+
+## 1. Ownership Model
+
+Given that integration tests touch multiple services, clear ownership is required to avoid abandoned tests and broken builds.
+
+- **Primary Owner (Initiator):** The team or developer that originates the feature requiring cross-repo coordination is the primary owner of the integration test. They are responsible for writing, maintaining, and debugging the test in the first instance.
+- **Secondary Owner (Consumer/Provider):** The team managing the downstream or upstream service being integrated with. They must review the integration tests to ensure they accurately represent the API contract and expected behaviors.
+
+## 2. Test Placement and Infrastructure
+
+- **Dedicated Integration Repo:** For complex multi-surface features, integration tests should be housed in a centralized `integration-tests` repository or a dedicated directory in the primary consumer's repository.
+- **CI/CD Triggers:** 
+  - Cross-repo tests run on nightly builds to avoid slowing down individual service PRs.
+  - On demand triggers can be executed via GitHub Actions `workflow_dispatch` with specific branch names for PRs that span multiple repos.
+
+## 3. Coordination Workflow
+
+1. **RFC / Design Phase:** Any feature spanning multiple repos must include an integration testing plan in its design document.
+2. **Contract Agreement:** Service contracts (e.g., OpenAPI, ABI) must be finalized and mockable before cross-repo integration tests are written.
+3. **Implementation:** The initiator writes the tests against staging/testnet environments.
+4. **Review:** Maintainers from all involved repositories must approve the PR introducing or modifying the integration tests.
+5. **Monitoring:** Failures in cross-repo tests should alert the `#integration-alerts` channel, tagging the Primary Owner.
+
+## 4. Environment Standardization
+
+Integration tests must be executed against ephemeral environments or dedicated staging instances that closely mirror production, utilizing seeded deterministic data to avoid flakiness.
diff --git a/docs/DEFINITION_OF_DONE.md b/docs/DEFINITION_OF_DONE.md
@@ -0,0 +1,43 @@
+# Definition of Done (DoD) for Multi-Surface Features
+
+Features that span across multiple surfaces (Backend, Frontend, Smart Contracts, Infrastructure) require a rigorous Definition of Done to ensure complete, secure, and maintainable delivery. 
+
+Use this checklist before marking a multi-surface feature as "Done".
+
+## 1. Smart Contracts
+- [ ] Code is fully implemented and peer-reviewed by at least two core maintainers.
+- [ ] 100% Unit test coverage achieved.
+- [ ] Fuzzing and invariant tests implemented and passing.
+- [ ] Slither / Static analysis run and all findings addressed or documented.
+- [ ] Gas optimization report generated and regressions justified.
+- [ ] Contract deployed to testnet and addresses documented.
+
+## 2. Backend & APIs
+- [ ] API endpoints implemented and matching the agreed-upon OpenAPI spec.
+- [ ] Database migrations created, tested (up/down), and reviewed.
+- [ ] Unit and Integration tests written and passing.
+- [ ] Logging (with correlation IDs) and metrics implemented for new flows.
+- [ ] Rate limiting and security constraints applied.
+
+## 3. Frontend
+- [ ] UI components implemented matching Figma designs.
+- [ ] State management handles loading, success, and error states gracefully.
+- [ ] E2E tests (Playwright/Cypress) written for the happy path of the new feature.
+- [ ] Feature is responsive across mobile and desktop breakpoints.
+- [ ] Web3 integration handles wallet disconnects, network switching, and pending transactions.
+
+## 4. Documentation
+- [ ] User-facing documentation/guides updated.
+- [ ] API documentation (Swagger/Postman) updated.
+- [ ] Runbooks and incident response procedures updated (if infra/ops changed).
+- [ ] Architecture diagrams updated (if new services/components added).
+
+## 5. Security & Observability
+- [ ] Threat modeling considered for the holistic feature.
+- [ ] Alerts and dashboards created for new critical metrics (e.g., failure rates).
+- [ ] Feature flagged appropriately (if using gradual rollout).
+
+## 6. Release Management
+- [ ] Cross-repo integration tests passing in the staging environment.
+- [ ] Deployment checklist and rollback plan created.
+- [ ] PR descriptions clearly link to all related PRs across different repositories.
diff --git a/docs/ISSUE_TAXONOMY_AND_LABELS.md b/docs/ISSUE_TAXONOMY_AND_LABELS.md
@@ -0,0 +1,41 @@
+# Repository-Wide Issue Taxonomy and Labeling Standards
+
+To maintain an organized and triagable backlog, all issues and pull requests must adhere to the following taxonomy and labeling standards.
+
+## 1. Category Labels (Type)
+Every issue must have exactly **one** type label:
+* `type: feature` - New functionality or enhancement.
+* `type: bug` - Something is broken or not behaving as intended.
+* `type: chore` - Maintenance, dependency updates, refactoring, or tooling.
+* `type: docs` - Documentation additions or improvements.
+* `type: security` - Security vulnerabilities or improvements (Note: sensitive issues should be reported via security policy, not public issues).
+
+## 2. Surface / Component Labels (Scope)
+Indicate which parts of the stack are affected (multiple allowed):
+* `scope: contracts` - Smart contracts, Solidity, Foundry.
+* `scope: backend` - Node.js, databases, indexers, APIs.
+* `scope: frontend` - React, Next.js, UI/UX, Web3 integration.
+* `scope: infra` - Deployment, Terraform, CI/CD, GitHub Actions.
+
+## 3. Severity / Priority Labels
+Bugs and critical tasks must have a priority:
+* `priority: critical` - Production down, funds at risk. Drop everything.
+* `priority: high` - Major feature broken, no workaround. Address in current sprint.
+* `priority: medium` - Minor bug, edge case, or has a workaround.
+* `priority: low` - Trivial issue, cosmetic bug, nice-to-have.
+
+## 4. Status / Workflow Labels
+Used by PMs and maintainers to track progress:
+* `status: needs-triage` - Default for new issues. Needs review.
+* `status: ready-for-dev` - Approved, specced out, and ready to be picked up.
+* `status: blocked` - Waiting on a dependency, external team, or design.
+* `status: in-progress` - Currently being worked on.
+
+## 5. Workstream / Epic Mapping
+For larger initiatives, issues should be tied to a specific workstream:
+* `epic: [Name]` - e.g., `epic: v2-vaults`, `epic: compliance-upgrade`.
+
+## Enforcing Standards
+* The triage bot will automatically flag issues missing a `type:` or `scope:` label.
+* PRs should inherit the labels of the issue they resolve.
+* Avoid creating custom labels without proposing them in the `#engineering` channel first.
diff --git a/docs/QUALITY_GATES_MATRIX.md b/docs/QUALITY_GATES_MATRIX.md
@@ -0,0 +1,37 @@
+# Quality Gates Matrix by Component Criticality
+
+This matrix defines the required quality gates, testing standards, and review processes based on the criticality of the component being modified.
+
+## Criticality Levels
+
+### Tier 1: Core Smart Contracts & Value Transfer
+*Components: Vault Contracts, Token Contracts, Oracle Integrations, Yield Strategies*
+- **Unit Test Coverage:** 100% (Line and Branch)
+- **Fuzzing/Invariant Testing:** Required (e.g., Echidna, Foundry)
+- **Static Analysis:** Slither & Aderyn (0 High/Med findings allowed without documented false positive)
+- **Audits:** External audit required for major releases
+- **Code Review:** Minimum 2 approvals from Core Contract Maintainers
+
+### Tier 2: Backend Services & API Layer
+*Components: Indexers, Transaction Relayers, Webhooks, Data APIs*
+- **Unit Test Coverage:** 90%+ 
+- **Integration Tests:** Required for all critical paths (deposits, withdrawals)
+- **Static Analysis:** SonarQube / ESLint with strict rules
+- **Load Testing:** Required for components handling high TPS
+- **Code Review:** Minimum 1 approval from Backend Maintainers
+
+### Tier 3: Frontend & User Interfaces
+*Components: Web Dashboard, Admin Panel, Mobile views*
+- **Unit Test Coverage:** 80%+ (Focus on utility functions and state management)
+- **E2E Testing:** Playwright/Cypress covering critical user journeys (Connect Wallet, Deposit, Withdraw)
+- **Accessibility (a11y):** Automated Lighthouse checks passing (Score > 90)
+- **Code Review:** Minimum 1 approval from Frontend Maintainers
+
+### Tier 4: Operational Tooling & Scripts
+*Components: Deployment scripts, CI/CD pipelines, internal CLI tools*
+- **Review:** 1 approval from DevOps / Infra Maintainer
+- **Testing:** Dry-run capabilities required. Bash scripts must pass `shellcheck`.
+- **Documentation:** Clear runbooks and inline comments required.
+
+## Enforcement
+These gates are enforced via GitHub Actions branch protection rules. Bypassing these gates requires explicit sign-off from the Tech Lead or Security Lead.