# EdgeVec Supreme Rule — Military-Grade Development Protocol
# Version: 1.1.0 | Correctness by Construction
---
alwaysApply: true
---
## 0. THE SUPREME MANDATE
> **"Design > Code. Validation > Speed. Correctness > Convenience."**
This workspace builds **EdgeVec**, a high-performance embedded vector database in Rust/WASM. We follow a **military-grade development protocol** where:
1. **No code is written without an approved plan.**
2. **No plan is created without approved architecture.**
3. **No artifact proceeds without HOSTILE_REVIEWER approval.**
---
## 1. THE FORBIDDEN ACTIONS
### 1.1 Code Without Plan — FORBIDDEN
```
❌ FORBIDDEN: Writing any code in `src/` before:
- ARCHITECTURE.md is approved by HOSTILE_REVIEWER
- WEEKLY_TASK_PLAN.md is approved by HOSTILE_REVIEWER
✅ ALLOWED: Writing code ONLY when the task is listed in
an APPROVED WEEKLY_TASK_PLAN.md
```
**Enforcement:** AI assistants MUST refuse to write implementation code unless they can reference an approved task ID (e.g., `W3.2`).
### 1.2 Plan Without Architecture — FORBIDDEN
```
❌ FORBIDDEN: Creating WEEKLY_TASK_PLAN.md before:
- ARCHITECTURE.md exists
- DATA_LAYOUT.md exists
- WASM_BOUNDARY.md exists
- All three are approved by HOSTILE_REVIEWER
✅ ALLOWED: Planning ONLY when architecture is approved
```
### 1.3 Bypassing Hostile Review — FORBIDDEN
```
❌ FORBIDDEN: Any artifact proceeding without explicit
HOSTILE_REVIEWER approval
✅ ALLOWED: Override ONLY with [HUMAN_OVERRIDE] tag and
documented justification
```
---
## 2. THE AGENT ROSTER
| Agent | Role | Output | Kill Authority |
|:------|:-----|:-------|:---------------|
| **PROMPT_MAKER** | Dispatcher | Prompts for other agents | NO |
| **META_ARCHITECT** | System design | `ARCHITECTURE.md`, `DATA_LAYOUT.md` | NO |
| **PLANNER** | Roadmap & tasks | `ROADMAP.md`, `WEEKLY_TASK_PLAN.md` | NO |
| **RUST_ENGINEER** | Core implementation | Rust code in `src/` | NO |
| **TEST_ENGINEER** | QA & Fuzzing | Tests, Fuzz targets, Regression suites | NO |
| **WASM_SPECIALIST** | Browser integration | WASM bindings, TypeScript | NO |
| **BENCHMARK_SCIENTIST** | Performance testing | Benchmark reports | NO |
| **HOSTILE_REVIEWER** | Quality gate | GO/NO_GO verdicts | **YES** |
| **DOCWRITER** | Documentation | README, API docs | NO |
### Agent Commands
All agents are invoked via `.cursor/commands/CMD_[AGENT].md`:
- `@PROMPT_MAKER` — Generate correct prompt for task
- `@META_ARCHITECT design [component]` — Design architecture
- `@PLANNER roadmap` — Create roadmap
- `@RUST_ENGINEER implement W[N].[X]` — Implement task
- `@TEST_ENGINEER prop [module]` — Write property tests
- `@WASM_SPECIALIST bind [function]` — Create WASM binding
- `@BENCHMARK_SCIENTIST baseline [component]` — Establish baseline
- `@HOSTILE_REVIEWER review [artifact]` — Execute hostile review
- `@DOCWRITER readme` — Generate README
---
## 3. THE WORKFLOW (GENESIS SEQUENCE)
```
┌──────────────────────────────────────────────────────────────────────┐
│ GENESIS WORKFLOW (RIGID SEQUENCE) │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 0: Setup │
│ ├── [x] Create .cursorrules (this file) │
│ ├── [x] Create agent command files │
│ └── [ ] Initialize Cargo project │
│ │
│ Phase 1: Architecture (No Code Allowed) │
│ ├── [ ] META_ARCHITECT creates ARCHITECTURE.md │
│ ├── [ ] META_ARCHITECT creates DATA_LAYOUT.md │
│ ├── [ ] META_ARCHITECT creates WASM_BOUNDARY.md │
│ └── [ ] HOSTILE_REVIEWER approves all three │
│ │
│ Phase 2: Planning (No Code Allowed) │
│ ├── [ ] PLANNER creates ROADMAP.md │
│ ├── [ ] HOSTILE_REVIEWER approves ROADMAP.md │
│ ├── [ ] PLANNER creates WEEKLY_TASK_PLAN.md (Week 1) │
│ └── [ ] HOSTILE_REVIEWER approves weekly plan │
│ │
│ Phase 3: Implementation (Code Allowed — For Approved Tasks Only) │
│ ├── [ ] RUST_ENGINEER implements approved tasks │
│ ├── [ ] TEST_ENGINEER adds fuzz/prop tests │
│ ├── [ ] WASM_SPECIALIST creates bindings │
│ ├── [ ] BENCHMARK_SCIENTIST validates performance │
│ ├── [ ] HOSTILE_REVIEWER validates deliverables │
│ └── [ ] Repeat weekly │
│ │
│ Phase 4: Polish & Launch │
│ ├── [ ] DOCWRITER creates README │
│ ├── [ ] HOSTILE_REVIEWER approves documentation │
│ └── [ ] Ship v0.1.0 │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## 4. QUALITY STANDARDS
### 4.1 Code Standards
| Standard | Requirement | Enforcement |
|:---------|:------------|:------------|
| **Testing** | 100% coverage for public API | `cargo tarpaulin` |
| **Verification** | Property tests for all algos | `proptest` |
| **Fuzzing** | Fuzzing for all parsers/inputs | `cargo fuzz` |
| **Formatting** | `cargo fmt` | CI blocks on failure |
| **Linting** | `cargo clippy -- -D warnings` | CI blocks on failure |
| **Safety** | No `unsafe` without proof | Code review |
| **Errors** | No `unwrap()` in library code | Code review |
### 4.2 Architecture Standards
| Standard | Requirement |
|:---------|:------------|
| **Struct Sizes** | All structs have documented size and alignment |
| **Memory Budget** | Calculated for 1M vectors |
| **WASM Boundary** | All exported functions are FFI-safe |
| **Performance Budget** | <10ms search for 100k vectors |
| **Persistence Format** | Magic number + version + checksum |
### 4.3 Planning Standards
| Standard | Requirement |
|:---------|:------------|
| **Task Size** | No task > 16 hours (must decompose) |
| **Estimation** | 3x rule applied to all estimates |
| **Acceptance** | Every task has binary pass/fail criteria |
| **Dependencies** | All dependencies are specific and verifiable |
---
## 5. HOSTILE GATE PROTOCOL
### 5.1 Gate Checkpoints
```
┌─────────────────────────────────────────────────────────────┐
│ GATE 1: Architecture → Planning │
│ Requires: HOSTILE_REVIEWER approval of: │
│ - ARCHITECTURE.md │
│ - DATA_LAYOUT.md │
│ - WASM_BOUNDARY.md │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ GATE 2: Planning → Implementation │
│ Requires: HOSTILE_REVIEWER approval of: │
│ - ROADMAP.md │
│ - WEEKLY_TASK_PLAN.md │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ GATE 3: Implementation → Merge │
│ Requires: HOSTILE_REVIEWER approval of: │
│ - All code changes │
│ - All unit/prop/fuzz tests pass │
│ - Benchmark validates performance │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ GATE 4: Documentation → Release │
│ Requires: HOSTILE_REVIEWER approval of: │
│ - README.md │
│ - API documentation │
│ - CHANGELOG.md │
└─────────────────────────────────────────────────────────────┘
```
---
## 6. DIRECTORY STRUCTURE
```
edgevec/
├── .cursor/
│ └── commands/
│ ├── CMD_PROMPT_MAKER.md # Dispatcher
│ ├── CMD_TEST_ENGINEER.md # QA/Fuzzing
│ ├── CMD_META_ARCHITECT.md
│ ├── CMD_PLANNER.md
│ ├── CMD_RUST_ENGINEER.md
│ ├── CMD_WASM_SPECIALIST.md
│ ├── CMD_BENCHMARK_SCIENTIST.md
│ ├── CMD_HOSTILE_REVIEWER.md
│ └── CMD_DOCWRITER.md
├── .cursorrules # This file
├── docs/
│ ├── architecture/
│ │ ├── ARCHITECTURE.md # System design
│ │ ├── DATA_LAYOUT.md # Memory layouts
│ │ └── WASM_BOUNDARY.md # WASM interface
│ ├── planning/
│ │ ├── ROADMAP.md # 6-month plan
│ │ ├── WEEKLY_TASK_PLAN.md # Current week
│ │ └── RISK_REGISTER.md # Known risks
│ ├── reviews/
│ │ └── [YYYY-MM-DD]_[artifact].md # Hostile reviews
│ └── benchmarks/
│ └── [YYYY-MM-DD]_report.md # Performance reports
├── src/
│ ├── lib.rs # Library root
│ ├── hnsw.rs # HNSW implementation
│ └── ...
├── benches/
│ └── ...
├── tests/
│ └── ...
├── fuzz/
│ └── ...
├── Cargo.toml
├── README.md
├── LICENSE
└── CHANGELOG.md
```
---
## 7. TECHNICAL CONSTRAINTS
### 7.1 Rust Constraints
| Constraint | Reason |
|:-----------|:-------|
| Edition 2021 | Modern Rust features |
| MSRV 1.70 | WASM stability |
| `#![no_std]` optional | Embedded support |
| No external C deps | WASM compatibility |
### 7.2 WASM Constraints
| Constraint | Reason |
|:-----------|:-------|
| Target: `wasm32-unknown-unknown` | Universal support |
| Bundle size < 500KB | Fast loading |
| No `std::thread` | Use `wasm-bindgen-rayon` |
| No `std::fs` | Use IndexedDB |
### 7.3 Performance Constraints
| Metric | Target | Constraint |
|:-------|:-------|:-----------|
| Search latency (100k) | <10ms | P99 |
| Insert latency | <2ms (Quant) / <5ms (F32) | Mean [UPDATED W6: Physical Limit for 1536d accepted] |
| Memory per vector | <100 bytes | Including index |
| Index load time | <500ms | 100k vectors |
---
## 8. SALVAGED CODE POLICY
### From binary_semantic_cache
The following code is **approved for salvage**:
| File | Lines | Function | Status |
|:-----|:------|:---------|:-------|
| `similarity.rs` | 286-292 | `hamming_distance_single` | ✅ APPROVED |
| `similarity.rs` | 308-310 | `distance_to_similarity` | ✅ APPROVED |
| `encoder.rs` | 316-336 | `project_single` | ✅ APPROVED |
| `encoder.rs` | 343-359 | `binarize_and_pack_single` | ✅ APPROVED |
**Attribution Required:**
```rust
// Adapted from binary_semantic_cache v1.0 (MIT License)
// Copyright (c) 2024 Matteo Panzeri
// Original: https://github.com/[user]/binary_semantic_cache
```
**Everything Else:** Must be written from scratch.
---
## 9. COMMUNICATION PROTOCOL
### 9.1 Agent Handoffs
Every agent must end their work with an explicit handoff:
```markdown
## [AGENT]: Task Complete
Artifacts generated:
- [List files]
Status: [PENDING_HOSTILE_REVIEW | READY_FOR_NEXT_PHASE]
Next: [HOSTILE_REVIEWER to validate | NEXT_AGENT to continue]
```
### 9.2 Status Tags
| Tag | Meaning |
|:----|:--------|
| `[DRAFT]` | Work in progress |
| `[PROPOSED]` | Ready for hostile review |
| `[APPROVED]` | Passed hostile review |
| `[REJECTED]` | Failed hostile review |
| `[REVISED]` | Updated after rejection |
---
## 10. EMERGENCY PROCEDURES
### 10.1 If Hostile Review Fails
1. Read rejection document carefully
2. Address ALL critical issues
3. Address ALL major issues
4. Update artifact with `[REVISED]` tag
5. Resubmit for hostile review
---
## REVISION HISTORY
| Version | Date | Change |
|:--------|:-----|:-------|
| 1.0.0 | 2025-12-04 | Initial EdgeVec Genesis Protocol |
| 1.1.0 | 2025-12-05 | Added TEST_ENGINEER and PROMPT_MAKER |
---
**END OF EDGEVEC SUPREME RULE**