# {{PROJECT_NAME}} - Quantum Computing AI Agent Rules

This project follows AgentBible research code principles for quantum computing.

## Mandatory Rules

### 1. Test Before Code
- REFUSE to write implementation without test specification
- Write test file FIRST, then implementation
- Ask "What are the test cases?" before writing quantum algorithms

### 2. Rule of 50
- Functions must be <= 50 lines
- If longer, STOP and refactor into smaller functions
- Each function does ONE thing

### 3. Type Everything
- Type hints on ALL function signatures
- Docstrings on ALL public functions (Google style)
- Run `mypy src/` before committing

### 4. Quantum Physical Validation (CRITICAL)
Always validate quantum constraints explicitly:

```python
from src.validation import (
    check_unitarity,           # U dagger U = I
    check_normalized,          # <psi|psi> = 1
    check_density_matrix,      # Hermitian, trace=1, positive semidefinite
    check_hermitian,           # H = H dagger
    check_probabilities,       # non-negative, sum=1
    check_cptp,                # Completely Positive Trace Preserving
    check_qubit_dimension,     # Dimension is 2^n
)
```

### 5. Quantum-Specific Requirements
- ALWAYS validate gate unitarity before use
- ALWAYS check state normalization after operations
- ALWAYS verify measurement probabilities sum to 1
- Use density matrices for mixed states and open systems
- Track quantum dimensions explicitly (n_qubits, 2^n Hilbert space)

### 6. No Silent Failures
- NEVER use bare `except:`
- ALWAYS log or re-raise with context
- Include what failed, expected value, actual value

### 7. Reproducibility
- Set random seeds explicitly for sampling
- Document seed values
- Use `tests/conftest.py` fixtures
- Use deterministic simulators when possible

## Project Structure

- Source code: `src/`
- Tests: `tests/`
- Run `pytest` before committing
- Minimum 70% test coverage

## Quantum Libraries

This template supports:
- **Framework-agnostic**: Pure numpy for custom implementations
- **Qiskit**: `pip install -e ".[qiskit]"`
- **Cirq**: `pip install -e ".[cirq]"`

## Before Committing

```bash
pytest                  # Tests pass
ruff check .            # No lint errors
mypy src/               # No type errors
```

## CI/CD Rules (CRITICAL)

### Always Verify CI After Push
After EVERY push to remote, you MUST verify CI status:
```bash
bible ci status         # Check workflow runs
# OR
gh run list --limit 5   # Alternative if bible not available
```

### If CI Fails
1. Check what failed: `gh run view <run-id> --log-failed`
2. Fix the issue locally
3. Push fix and verify again
4. NEVER tell the user "CI should pass" without checking

## Common Quantum Pitfalls

1. **Global phase**: Quantum states are equivalent up to global phase
2. **Numerical precision**: Use tolerance ~1e-10 for unitarity checks
3. **Qubit ordering**: Be explicit about little-endian vs big-endian
4. **Measurement collapse**: State is destroyed after measurement
5. **Entanglement**: Cannot factor entangled states into tensor products
