# Waterline Freeze Checklist

**Purpose**: Actionable checklist for verification cycles (gates, retests, releases)

**Environment**: All verification uses canonical contexts per [docs/operations/verifier-environment-spec.md](verifier-environment-spec.md)

---

## Pre-Verification Checklist

Complete ALL items before proceeding with verification cycle.

> **Freeze Protocol Evidence Required**: Every verification cycle must capture
> evidence for auditability. See [Freeze Protocol section in waterline-freeze-policy.md](waterline-freeze-policy.md#freeze-protocol).

### 0. Capture Freeze Evidence

**Required for all verification cycles**:

```bash
# Evidence: git rev-parse HEAD
echo "Commit: $(git rev-parse HEAD)" | tee /tmp/freeze_evidence.log

# Evidence: git status clean
git status --short | tee -a /tmp/freeze_evidence.log
[ -z "$(git status --short)" ] && echo "✓ Clean" || echo "✗ Dirty"

# Evidence: environment declaration (canonical: use project venv)
# See docs/operations/verifier-environment-spec.md for context
uname -a | tee -a /tmp/freeze_evidence.log
uv run python --version | tee -a /tmp/freeze_evidence.log

# Evidence: no-code-change assertion
echo "Freeze baseline: $(git rev-parse HEAD)" | tee -a /tmp/freeze_evidence.log
echo "Verified at: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a /tmp/freeze_evidence.log
```

| Evidence Field | Command | Expected |
|----------------|---------|----------|
| Git HEAD | `git rev-parse HEAD` | Full 40-char SHA |
| Git Status | `git status --short` | Empty (clean) |
| Environment | `uname -a` & `uv run python --version` | Recorded |
| No-Code-Change | `git diff $FREEZE_COMMIT` | No diff |

- [ ] `git rev-parse HEAD` captured
- [ ] `git status --short` shows clean (empty output)
- [ ] Environment declared (OS, Python version)
- [ ] No-code-change assertion verified

### 1. Capture Current State

```bash
# Run guard and save output
uvx invar-tools guard --all > /tmp/guard_current.json

# Verify command succeeded
echo $?  # Should output 0
```

- [ ] Guard output captured to `/tmp/guard_current.json`
- [ ] Exit code is 0

### 2. Extract Metrics

```bash
# Quick metrics extraction
uvx invar-tools guard --all | jq '{
  status: .status,
  errors: .static.errors,
  warnings: .static.warnings,
  escape_hatches: .escape_hatches.count
}'
```

Fill in current values:

| Metric | Baseline | Current | Pass? |
|--------|----------|---------|-------|
| Guard Status | passed | _______ | [ ] |
| Errors | 0 | _______ | [ ] |
| Warnings | 56 (max 56) | _______ | [ ] |
| Escape Hatches | 272 (max 272) | _______ | [ ] |

### 3. Validate Non-Regression

**Hard Constraints** (MUST pass):

- [ ] Guard status is `"passed"`
- [ ] Errors = 0
- [ ] Warnings ≤ 56
- [ ] Escape hatches ≤ 272

**If ANY hard constraint fails**: STOP and remediate before proceeding.

### 4. Check for New Warnings

```bash
# List new warnings (if any)
diff <(cat /tmp/guard_baseline.json | jq -r '.fixes[] | select(.severity == "warning") | .message') \
     <(cat /tmp/guard_current.json | jq -r '.fixes[] | select(.severity == "warning") | .message')
```

- [ ] No new high-severity warnings introduced
- [ ] If new warnings exist, they are documented with justification

### 5. Contract Coverage Check

```bash
# Check contract coverage warnings
uvx invar-tools guard --all | jq '.fixes[] | select(.rule == "contract_quality_ratio")'
```

- [ ] Contract coverage warnings remain below threshold
- [ ] No new modules with < 80% coverage (unless exempted)

---

## Verification Cycle Types

### Gate Verification

**When**: Before merge to main branch

**Additional Checks**:
- [ ] All tests pass, including repro scripts (run `uv run pytest tests/`)
- [ ] All changed files pass guard (run `invar guard` without `--all`)
- [ ] No new escape hatches without justification
- [ ] Documentation updated if behavior changed

**Command**:
```bash
# Run all tests (including repro scripts)
uv run pytest tests/ -v --tb=short

# Check only changed files (faster)
invar guard

# Check all files (comprehensive)
invar guard --all
```

### Retest Verification

**When**: After bug fix or refactor

**Additional Checks**:
- [ ] Guard warnings not increased
- [ ] Escape hatch count not increased
- [ ] Test coverage maintained or improved

**Command**:
```bash
# Full verification
uvx invar-tools guard --all && echo "✓ Retest check passed"
```

### Release Verification

**When**: Before release tag

**Additional Checks**:
- [ ] All gate verification checks pass
- [ ] Waterline baseline metrics updated in `docs/operations/waterline-freeze-policy.md`
- [ ] No pending exceptions or temporary regressions
- [ ] Changelog updated with quality improvements

**Command**:
```bash
# Complete release verification
uvx invar-tools guard --all | tee /tmp/release_guard.json
cat /tmp/release_guard.json | jq '
   if .static.errors == 0 and .static.warnings <= 56
  then "✓ RELEASE READY"
  else "✗ NOT READY FOR RELEASE"
  end
'
```

---

## Exception Handling

### When Waterline Fails

**STOP**: Do NOT proceed with verification until resolved.

**Steps**:

1. **Document Failure**:
   ```bash
   # Save failure details
   uvx invar-tools guard --all > /tmp/guard_failure.json
   echo "Waterline failed at $(date)" >> /tmp/waterline_failures.log
   ```

2. **Classify Failure**:
   - [ ] New static error → MUST fix immediately
   - [ ] Warnings budget exceeded → MUST fix or justify
   - [ ] Escape hatch budget exceeded → MUST refactor or justify
   
3. **Remediate or Request Exception**:
   - Fix the issue if possible
   - If exception needed:
     - Document reason in code with `# @invar:allow` and justification
     - Create tracking issue for resolution
     - Get approval from code owner

4. **Re-verify**:
   ```bash
   uvx invar-tools guard --all
   ```
   Repeat until waterline passes.

---

## Quick Reference Commands
### Automated Gate (CI + Local)
```bash
# Same command CI executes in .github/workflows/waterline-gate.yml
uv run python scripts/waterline_guard_gate.py
```

**Fail-fast criteria order** (from freeze policy hard constraints):
1. Guard status must be `passed`
2. Static errors must remain `0`
3. Static warnings must stay `<= 56`
4. Escape hatches must stay `<= 272`
5. Contract coverage for frozen modules must not regress below baseline (`models.py >= 20%`, `errors.py >= 13%`)


### Waterline Status (One-Liner)
```bash
uvx invar-tools guard --all | jq '
   if .static.errors == 0 and .static.warnings <= 56 and .escape_hatches.count <= 272
  then "✓ WATERLINE PASS"
  else "✗ WATERLINE FAIL"
  end
'
```

### Metrics Dashboard
```bash
uvx invar-tools guard --all | jq '{
  status: .status,
  errors: .static.errors,
  warnings: .static.warnings,
  files: .summary.files_checked,
  escapes: .escape_hatches.count
}'
```

### Warning Count
```bash
uvx invar-tools guard --all | jq '.static.warnings'
```

### Escape Hatch Count
```bash
uvx invar-tools guard --all | jq '.escape_hatches.count'
```

---

## Baseline Metrics Reference

**Last Updated**: 2026-03-07
**Source**: `docs/operations/waterline-freeze-policy.md`

| Metric | Baseline | Budget |
|--------|----------|--------|
| Guard Status | passed | Must PASS |
| Errors | 0 | Max 0 |
| Warnings | 56 | Max 56 |
| Infos | 11 | Max 11 |
| Files Checked | 69 | N/A |
| Escape Hatches | 272 | Max 272 |

**Contract Coverage**:
- `core/schemas/models.py`: 20% (exemption: Pydantic validators)
- `core/schemas/errors.py`: 13% (exemption: Error boilerplate)

**Budget Usage**:
- Warning budget: 56/56 (100% used)
- Escape hatch budget: 272/272 (100% used)

---

## Post-Verification Actions

### After Successful Verification

- [ ] Save guard output for audit trail
- [ ] Update baseline if metrics improved
- [ ] Document any quality improvements

### After Failed Verification

- [ ] Create issue for failure
- [ ] Document remediation steps taken
- [ ] Schedule follow-up verification

### After Exception Granted

- [ ] Document exception in code
- [ ] Create tracking issue with due date < 1 sprint
- [ ] Add to technical debt backlog
- [ ] Re-verify after resolution

---

## Checklist Template (Copy-Paste)

```markdown
## Waterline Verification - [DATE]

**Cycle Type**: [ ] Gate  [ ] Retest  [ ] Release

### Metrics

| Metric | Baseline | Current | Pass? |
|--------|----------|---------|-------|
| Status | passed | | [ ] |
| Errors | 0 | | [ ] |
| Warnings | 56 | | [ ] |
| Escapes | 272 | | [ ] |

### Result

[ ] **PASS** - All constraints satisfied
[ ] **FAIL** - Remediation required

**Notes**: 
```

---

*Automated enforcement: Use `invar guard` in CI/CD pipelines*
