# Windsurf-Hooker: Mission & Enforcement Vision
## Mission Statement
**Windsurf-Hooker enforces comprehensive code quality standards at the IDE level, ensuring that all code written through Windsurf is:**
1. ✅ **100% Implemented** - No TODOs, no stubs, no placeholders
2. ✅ **Thoroughly Documented** - Every function has a docstring, complex logic has inline comments
3. ✅ **Debuggable by Default** - Meaningful names, clear intent, traceable execution
4. ✅ **Production-Grade** - Real working code, not simplified or mock implementations
5. ✅ **Secure** - No escape primitives, no unauthorized execution, plan-authorized only
This happens **before** code reaches ATLAS-GATE MCP, providing immediate IDE-level feedback.
---
## The Problem Windsurf-Hooker Solves
### Without Windsurf-Hooker
```
Developer Windsurf IDE ATLAS-GATE Server
│ │ │
│─ "Write email validator"───>│ │
│ <writes code with TODO> │
│ │─ Transmit code ─────────────────>│
│ │ GATE 4: detectStubs()
│ │ ❌ BLOCKED: Contains TODO
│ │<── Error: Code has unfinished work
│<─ Reject: Fix your code ────│
│
│─ "Remove TODO and rewrite"─>│
│ <rewrites code>
│ │─ Transmit ──────────────────────>│
│ │ ✅ ACCEPTED
│<─ Done: 2 round trips!
```
**Problems:**
- Network overhead (unnecessary transmission)
- Slow iteration (wait for server response)
- Frustration (should have been caught locally)
- Resource waste (server processes invalid code)
### With Windsurf-Hooker
```
Developer Windsurf IDE ATLAS-GATE Server
│ │ │
│─ "Write email validator"───>│ │
│ <writes code with TODO> │
│ pre_write_completeness │
│ ❌ BLOCKED: Contains TODO │
│<─ Immediate error in IDE ───│
│
│─ "Fix the TODO"────────────>│
│ <fixes code>
│ All 10 gates pass ✅
│ │─ Transmit ──────────────────────>│
│ │ All 5 ATLAS-GATE gates pass ✅
│<─ Done: Fast, immediate feedback!
```
**Benefits:**
- Fast iteration (hook feedback in milliseconds)
- Developer experience (clear, immediate errors)
- Bandwidth efficiency (no rejected transmissions)
- Resource efficiency (server only processes good code)
- Consistent standards (same gates everywhere)
---
## Windsurf-Hooker vs ATLAS-GATE: Complementary Roles
### Windsurf-Hooker: Pre-Execution (IDE-Level)
**When:** Before transmission to server
**Where:** Windsurf IDE, on developer's machine
**Speed:** Milliseconds (local Python execution)
**Purpose:** Developer feedback + productivity
**Scope:** Local code quality, intent, completeness
**Configurability:** Policy-driven, editable
**Enforces:**
- ✅ No TODOs, FIXMEs, stubs
- ✅ All functions documented
- ✅ Complex code has comments
- ✅ No bad variable names
- ✅ No escape primitives (subprocess, socket, etc.)
- ✅ Prohibited patterns (mocks, placeholders)
- ✅ Diff quality (no massive changes)
### ATLAS-GATE MCP: Post-Execution (Server-Level)
**When:** After transmission to server
**Where:** Kubernetes pod, centralized
**Speed:** Milliseconds but includes plan lookup + hash verification
**Purpose:** Authoritative enforcement + audit trail
**Scope:** Workspace integrity, plan authority, forensic record
**Configurability:** Fixed governance, not editable per-user
**Enforces:**
- ✅ Plan exists and authorizes change
- ✅ Role metadata valid
- ✅ Preflight tests pass (build not broken)
- ✅ Language-specific rules (Rust unwrap, TS any)
- ✅ Audit trail recorded + hash chain verified
- ✅ Workspace integrity maintained
### Together: Defense-in-Depth
```
Developer Intent
↓
┌─────────────────────┐
│ Windsurf-Hooker │ ← Fast, iterative, feedback-focused
│ (10 local gates) │
└──────────┬──────────┘
↓ (code passes)
Network transmission
↓
┌─────────────────────┐
│ ATLAS-GATE MCP │ ← Authoritative, governance-focused
│ (5 server gates) │
└──────────┬──────────┘
↓ (code passes)
Production workspace
```
**Key insight:** Windsurf-Hooker shifts enforcement LEFT (to developer), while ATLAS-GATE provides RIGHT (server-side backup). Both are required to pass.
---
## Current State: 10 Hooks Implemented
### Existing Hooks (3)
1. ✅ `pre_write_code_escape_detection.py` - Blocks subprocess, socket, etc.
2. ✅ `pre_write_code_policy.py` - Enforces prohibited patterns
3. ✅ `pre_write_diff_quality.py` - Quality warnings (not blocking)
### New Hooks (Phase 1 - Now Implemented)
4. ✅ `pre_write_completeness.py` - Blocks TODOs, stubs, placeholders
5. ✅ `pre_write_comprehensive_comments.py` - Enforces documentation
### Supporting Hooks (Also Enforcing)
6. ✅ `pre_user_prompt_gate.py` - Requires canonical prompt
7. ✅ `pre_intent_classification.py` - Validates intent
8. ✅ `pre_plan_resolution.py` - Verifies plan exists
9. ✅ `pre_mcp_tool_use_atlas_gate.py` - Tool allowlist
10. ✅ `pre_run_command_kill_switch.py` - Command blocking
---
## What Gets Enforced Now
### Completeness (NEW Hook #4)
```python
# ❌ BLOCKED
def process_user():
# TODO: implement
pass
# ✅ ALLOWED
def process_user(user: User) -> Result:
"""Process user and return result."""
return do_processing(user)
```
Blocks:
- TODO, FIXME, XXX, HACK, BUG, TEMP comments
- `pass` statements (outside except blocks)
- `NotImplementedError`, `unimplemented!()`
- Placeholder returns (None, {}, [])
- Functions with no implementation
### Documentation (NEW Hook #5)
```python
# ❌ BLOCKED - Missing docstring
def calculate_total(items):
total = 0
for item in items:
total += item.price
return total
# ✅ ALLOWED - Has documentation
def calculate_total(items: List[Item]) -> float:
"""
Sum all item prices in a list.
Args:
items: List of items with price attribute
Returns:
Total price of all items
"""
total = 0
for item in items:
total += item.price # Accumulate item cost
return total
```
Requires:
- Docstring for every function/class
- Meaningful inline comments for complex code
- Meaningful variable names (not `x`, `temp`, `data`)
- Docstrings for functions > 5 lines
---
## Vision: Complete Enforcement System
### Phase 1 ✅ (Complete)
1. Escape primitives (subprocess, socket, etc.)
2. Prohibited patterns (mocks, hacks)
3. Completeness (no TODOs, stubs)
4. Documentation (docstrings, comments)
### Phase 2 (Planned)
5. Code quality (function length, complexity, error handling)
6. Debuggability (meaningful error messages, state traceability)
### Phase 3 (Planned)
7. Type safety (annotation validation)
8. Performance (no obvious inefficiencies)
---
## Architecture: How It Works
```
Windsurf IDE
├─ User types code
│
├─ Hook: pre_write_completeness
│ └─ Checks for TODOs, stubs
│ ├─ ✅ Found: None → Continue
│ └─ ❌ Found: TODO → BLOCK (exit 2)
│
├─ Hook: pre_write_comprehensive_comments
│ └─ Checks for docstrings, comments
│ ├─ ✅ Found adequate docs → Continue
│ └─ ❌ Found missing docs → BLOCK (exit 2)
│
└─ All hooks pass
└─ Transmit to ATLAS-GATE MCP → Workspace updated
```
---
## Impact on Development
### Before Phase 1
- Developer could write incomplete code
- Windsurf would send it to server
- Server would reject with `detectStubs()`
- Developer gets error 2-3 seconds later
- Developer must fix and resubmit
### After Phase 1
- Developer writes incomplete code
- Windsurf hook rejects immediately (100ms)
- Red error shows in IDE right away
- Developer fixes on the spot
- Code is clean when submitted
**Difference:** 2-3 second round trip → instant local feedback
---
## Configuration: Enforcement Levels
### Standard Mode (Default)
```json
{
"execution_profile": "standard",
"mcp_tool_allowlist": ["begin_session", "write_file", ...],
"prohibited_patterns": {...}
}
```
All hooks enforce. Code must be complete and documented.
### Execution-Only Mode
```json
{
"execution_profile": "execution_only",
"mcp_tool_allowlist": ["begin_session", "write_file"],
"block_commands_regex": [".*"]
}
```
Same code quality hooks PLUS no shell execution, no direct filesystem access.
### Panic/Locked Mode
```json
{
"execution_profile": "locked"
}
```
All code writes blocked. System is in lockdown. Contact admin to unlock.
---
## Validation Tests
### Test 1: Completeness
```bash
# Should BLOCK
echo '{"tool_info": {"edits": [{"path": "test.py", "new_string": "# TODO\npass"}]}}' | \
python3 windsurf-hooker/windsurf-hooks/pre_write_completeness.py
# Exit: 2 ✅
# Should ALLOW
echo '{"tool_info": {"edits": [{"path": "test.py", "new_string": "def foo():\n return 42"}]}}' | \
python3 windsurf-hooker/windsurf-hooks/pre_write_completeness.py
# Exit: 0 ✅
```
### Test 2: Documentation
```bash
# Should BLOCK
echo '{"tool_info": {"edits": [{"path": "test.py", "new_string": "def foo(x):\n return x * 2"}]}}' | \
python3 windsurf-hooker/windsurf-hooks/pre_write_comprehensive_comments.py
# Exit: 2 ✅
# Should ALLOW
echo '{"tool_info": {"edits": [{"path": "test.py", "new_string": "def foo(x):\n \"\"\"Double x.\"\"\"\n return x * 2"}]}}' | \
python3 windsurf-hooker/windsurf-hooks/pre_write_comprehensive_comments.py
# Exit: 0 ✅
```
---
## Philosophy: Code Quality is Not Optional
Windsurf-Hooker enforces a simple principle:
> **Code must be done, not sketched.**
This means:
- No TODOs (work is complete or we don't write it)
- No stubs (every function is implemented)
- No mocks (we use real data or test in isolation)
- No placeholders (every value means something)
- No undocumented code (you explain your thinking)
This is NOT hostile to developers. It's **liberating**:
- Fast feedback (know immediately if code is good)
- Clear standards (understand what "done" means)
- Confidence (know your code is production-ready)
- Maintainability (future developers understand intent)
---
## Summary
Windsurf-Hooker is the **IDE-level quality assurance system**:
1. **Enforces completeness** - No TODOs, stubs, or placeholders
2. **Requires documentation** - Every function documented, complex code explained
3. **Prevents escapes** - No subprocess, socket, or unauthorized execution
4. **Validates authority** - Only plan-authorized writes allowed
5. **Provides fast feedback** - Errors in milliseconds, not seconds
Together with ATLAS-GATE MCP, it creates a **comprehensive defense-in-depth system** that ensures:
- Code quality is enforced (Windsurf-Hooker)
- Governance is maintained (ATLAS-GATE)
- Production is protected (both systems)
This is the future of AI-assisted code: **smart, fast, safe, and complete**.
---
## Status: Phase 1 Complete ✅
✅ Windsurf-Hooker has 10 enforcement hooks
✅ Completeness checking implemented
✅ Documentation enforcement implemented
✅ Shift-left enforcement in place
✅ Compatible with ATLAS-GATE MCP
✅ Ready for production deployment
🎯 **Result:** From "code gets rejected at server" to "code never leaves local IDE unless it's complete and documented"
