# Verifier Environment Specification

> **Purpose:** Define canonical interpreter environment for gate verification to ensure reproducible import checks across different verifier contexts.

**Status**: ACTIVE
**Effective Date**: 2026-03-04
**Version**: 1.0

---

## Canonical Verification Environment

### Interpreter Context

Gate verification commands MUST use the **project's virtual environment** as the canonical interpreter context. This ensures:

1. Dependencies declared in `pyproject.toml` are available
2. Import checks reflect actual project runtime behavior
3. Verification is reproducible across different machines

### Command Conventions

| Command Type | Canonical Form | Environment |
|--------------|----------------|-------------|
| **Import verification** | `uv run python -c "import <module>"` | Project venv (via `uv run`) |
| **Dependency check** | `uv run python -c "import <module>; print(<module>.__version__)"` | Project venv |
| **Guard verification** | `uvx invar-tools guard --all` | Isolated (`uvx`) |
| **Environment info** | `uv run python --version` | Project venv |

### Environment Evidence

When capturing verification evidence, include:

```bash
# Environment declaration (canonical)
echo "Environment: $(uname -s) $(uname -m)"
uv run python --version | tee -a evidence.log

# Not: python3 --version (uses system Python, may differ)
```

---

## Rationale

### Why `uv run python` for Imports?

**`uv run python`**:
- Uses project's virtual environment (created/managed by `uv`)
- Has access to all dependencies in `pyproject.toml`
- Matches the environment where the code actually runs
- Resolves dependency version constraints

**System `python3`**:
- Uses system-installed Python
- May have different version than project requires
- May lack dependencies installed via `uv pip install`
- May have different packages installed
- **NOT suitable** for import verification

### Why `uvx invar-tools` for Guard?

**`uvx`**:
- Runs tools in isolated environments
- Always available (no install required)
- Does not pollute project dependencies
- Consistent across all machines
- Recommended BY THE PROJECT ITSLEF (see CLAUDE.md tool selection)

---

## Migration Guide

### Before (Ambiguous)

```bash
# ❌ WRONG: Mixed contexts, unclear environment
python3 --version              # System Python
uv run python -c "import X"    # Project venv
uvx invar-tools guard --all   # Isolated
```

### After (Canonical)

```bash
# ✅ CORRECT: Consistent environment context
uv run python --version                    # Project venv
uv run python -c "import X; print(X.ver)"  # Project venv
uvx invar-tools guard --all                # Isolated (guard tool)
```

---

## Affected Documentation Files

This specification updates the following files:

1. **docs/operations/waterline-freeze-policy.md**
   - Replace `python3 --version` with `uv run python --version`
   - Add environment context note

2. **docs/operations/waterline-checklist.md**
   - Replace environment capture commands
   - Clarify import verification steps

3. **docs/gate-*.md** (any gate verification logs)
   - Standardize on `uv run python` for import checks
   - Document which environment each command uses

---

## Verification Example

### Correct Verification Sequence

```bash
# 1. Environment declaration (canonical)
echo "Environment: $(uname -s) $(uname -m)"
uv run python --version

# 2. Import verification (project venv)
uv run python -c "import fastmcp; print(f'fastmcp {fastmcp.__version__}')"

# 3. Guard verification (isolated)
uvx invar-tools guard --all

# 4. Metrics extraction (isolated)
uvx invar-tools guard --all | jq '{status, errors: .static.errors, ...}'
```

### Evidence Template

```markdown
## Verification Evidence

**Commit**: <sha>
**Date**: <date>

### Environment
- OS: `uname -s` `uname -m`
- Python: `uv run python --version`
- Guard: `uvx invar-tools --version`

### Commands
1. Run: `uv run python -c "import fastmcp"` → ✅ SUCCESS
2. Run: `uvx invar-tools guard --all` → ✅ PASSED
3. Run: `uvx invar-tools guard --all | jq '.summary'` → `{"warnings": 13, ...}`

### Results
- Guard status: PASSED
- Errors: 0
- Warnings: 13/15 (budget: 87%)
- Escapes: 182/200 (budget: 91%)
```

---

## Background: The Ambiguity Issue

### Historical Problem

The codebase previously used ambiguous interpreter contexts:

1. **`python3 --version`** (waterline-freeze-policy.md line 137)
   - Uses system Python
   - May differ from project environment
   - Imports may fail even if project is correct

2. **`uv run python -c "import X"`** (gate-2026-03-04-warning-budget.md line 162)
   - Uses project venv
   - Correct for import checks
   - But mixed with system Python elsewhere

3. **`uvx invar-tools guard`** (consistent, but context unclear)
   - Isolated environment for tools
   - Should not be used for project imports

This led to verification failures where:
- System Python lacked dependencies
- Import checks failed despite correct project setup
- Verifiers had to guess which environment to use

### Resolution

This specification resolves the ambiguity by:
- Defining `uv run python` as canonical for project imports
- Defining `uvx invar-tools` as canonical for verification tools
- Banning `python3` in verification contexts (unless checking system requirements)
- Providing evidence templates with explicit environment declarations

---

## Compliance

All verification documentation MUST follow this specification.

**Non-compliance indicators**:
- ❌ Using `python3` without context comment
- ❌ Using system Python for import checks
- ❌ Missing environment declaration in evidence
- ❌ Ambiguous "verify import" without specifying `uv run`

**Compliant patterns**:
- ✅ `uv run python -c "import X"` for import checks
- ✅ `uvx invar-tools guard` for verification
- ✅ `uv run python --version` for environment evidence
- ✅ Explicit environment context in documentation

---

*Effective immediately. All verification documentation should be updated to align with this specification.*