---
type: skill
domain: development
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# CODE_VANGUARD.md
> **ROLE:** TECH LEAD
> **TRIGGER:** "CODE GEN"

## Protocol: 5-Step Code Standards Enforcement

1. **Brain Check** -- Run `brain_query.py --query "code standards <module>"` and check `Hippocampus/Patterns/` for known bad patterns.
2. **File Organization** -- Every Python file: docstring, stdlib imports, third-party imports, local imports, CONSTANTS, classes/functions, `if __name__ == "__main__":` guard last.
3. **Naming Conventions** -- `snake_case` functions/vars, `PascalCase` classes, `UPPER_SNAKE` constants, `is_/has_/can_` booleans, `_` prefix for private.
4. **Docstrings & Types** -- Every public function gets type hints and a docstring explaining purpose and return value. One-liner for simple functions, multi-line for complex.
5. **Size Gates** -- Functions <= 50 lines, files <= 300 lines (Law 7), classes <= 200 lines. Split immediately on violation.

## Metrics & Thresholds

| Metric | Threshold | Action |
|--------|-----------|--------|
| Function length | <= 50 lines | Extract helper functions |
| File length | <= 300 lines | Split module per Law 7 |
| Type hint coverage | 100% public API | Add hints before merge |
| Docstring coverage | 100% public funcs | Add docstrings before merge |

## Good Example

```python
"""Atomic task board operations for PULSE worker daemons."""
import json                          # stdlib
from filelock import FileLock        # third-party

_LOCK_TIMEOUT = 10

def claim_next_task(board_path: str, agent_name: str) -> dict | None:
    """Atomically claim the highest-priority unclaimed task."""
    lock = FileLock(f"{board_path}.lock", timeout=_LOCK_TIMEOUT)
    with lock:
        tasks = _load_board(board_path)
        task = _find_unclaimed(tasks)
        if task:
            task["claimed_by"] = agent_name
            _save_board(board_path, tasks)
    return task
```

## Anti-Patterns

- **`sys.exit()` in library code** -- Uncatchable by `except Exception`. Use `raise RuntimeError(msg)`.
- **Bare `except:`** -- Catches KeyboardInterrupt/SystemExit. Use `except Exception`.
- **Module-level side effects** -- Code at import time breaks importability. Guard with `__name__ == "__main__"`.

## Tools to Use

- `brain_query.py --query "code standards <module>"` -- Find past style issues
- `pulse_save.py --agent <you> --learnings "code pattern: <what worked>"` -- Record patterns
- `pulse_relay.py --tasks "Refactor <file> per Law 7:development:fast"` -- Delegate splits

## Verification Checklist

- [ ] Imports ordered: stdlib, third-party, local (3 blocks)
- [ ] All public functions have type hints and docstrings
- [ ] No function > 50 lines, no file > 300 lines
- [ ] Naming: snake_case functions, PascalCase classes, UPPER constants
- [ ] No `sys.exit()` in library code, no bare `except:`, no module-level side effects
