# Verification Policy

## Authoritative Command

**`invar guard` is the single source of truth for all code verification.**

Direct invocation of underlying tools (pytest, crosshair, hypothesis, mypy, ruff) is NOT authoritative for this project. Use `invar guard` instead.

## Why This Policy Exists

### Problem: Direct CrossHair Commands Appear to Skip Functions

Running `crosshair check src/lattice/core/llm_parser.py` produces:

```
WARNING: Targets found, but contain no checkable functions.
```

With verbose output:
```
Skipping extract_claude_text because CrossHair is not enabled
Skipping extract_opencode_text because CrossHair is not enabled
Skipping extract_text_from_jsonl because CrossHair is not enabled
```

This is misleading — the functions ARE checked, but by `invar guard`'s integrated verifier:

```
$ invar guard src/lattice/core/llm_parser.py
{
  "status": "passed",
  "crosshair": {
    "status": "verified",
    "verified": [],
    "cached": ["/Users/tefx/Projects/lattice/src/lattice/core/llm_parser.py"]
  }
}
```

### Root Cause

1. **deal decorators**: This project uses `@deal.pre`/`@deal.post` contracts. Direct `crosshair check` doesn't automatically enable verification for these without the proper plugin/config.

2. **invar integration**: `invar guard` includes custom integration that:
   - Enables CrossHair for deal-decorated functions
   - Respects `@skip_property_test` markers
   - Handles `# crosshair: off` comments
   - Provides caching for faster subsequent runs

3. **unified output**: `invar guard` combines static analysis + doctests + CrossHair + Hypothesis in one command.

## Verification Commands

| For | Use | NOT This |
|-----|-----|----------|
| All checks | `invar guard` | pytest, crosshair check, mypy |
| Changed files only | `invar guard` | `invar guard --changed` (changed is default) |
| Full project | `invar guard --all` | N/A |
| Quick static check | `invar guard --static` | ruff check, mypy |
| Contract coverage only | `invar guard --contracts-only` | N/A |

## Example: llm_parser.py

The module `src/lattice/core/llm_parser.py` demonstrates all three verification mechanisms:

### 1. Doctests (always verified)

```python
def extract_claude_text(data: dict[str, Any]) -> str | None:
    """Extract text from Claude CLI JSON output.
    >>> extract_claude_text({"content": [{"type": "text", "text": "Hello"}]})
    'Hello'
    """
```

### 2. Deal contracts (verified by invar guard's CrossHair integration)

```python
@deal.pre(lambda data: isinstance(data, dict))
@deal.post(lambda result: result is None or isinstance(result, str))
def extract_claude_text(data: dict[str, Any]) -> str | None:
    ...
```

### 3. Skip markers (respected by invar guard)

For functions that cannot be symbolically executed:

```python
# crosshair: off
@skip_property_test("crosshair_incompatible: json.loads triggers CrossHairInternal")
@deal.post(lambda result: result is None or isinstance(result, str))
def extract_text_from_jsonl(text: str) -> str | None:
    ...
```

## Verification Evidence Requirements

When completing a task that modifies Core functions, provide:

```yaml
status: completed
evidence:
  - command: invar guard src/lattice/core/my_module.py
    output: |
      {"status": "passed", "crosshair": {"status": "verified"}}
  - command: python -m doctest src/lattice/core/my_module.py -v
    output: |
      1 items passed all tests
```

## Why NOT Direct CrossHair?

| Issue | Direct `crosshair check` | `invar guard` |
|-------|-------------------------|---------------|
| Deal contract support | Requires manual plugin config | Built-in |
| `@skip_property_test` | Not recognized | Recognized and documented |
| `# crosshair: off` | Comments not parsed | Parsed and respected |
| Output format | Human text only | JSON + human (for CI) |
| Caching | None | Per-file caching |
| Combined verification | Run separately | One command |

## Integration with CI

CI pipelines should use:

```yaml
- name: Verify code quality
  run: invar guard --all
```

This is equivalent to running:
- mypy (type checking)
- ruff (linting)
- pytest --doctest-modules (doctests)
- crosshair (contract verification)
- hypothesis (property tests)

---

*Last updated: 2025-02-23*
*Related: INVAR.md § Troubleshooting, RFC-002 § Verification*