# Colibri Tools

This directory contains utility tools for the Colibri multiagent development workflow.

## proof-gate-tracker

Automated proof gate validation tool that checks the status of all 6 migration proof gates.

### Usage

```bash
# Build and run
cargo run --release --bin proof-gate-tracker

# Or build and run directly
cargo build --release --bin proof-gate-tracker
./target/release/proof-gate-tracker
```

### Proof Gates Checked

1. **Gate #1 - Contracts**: Validates golden test fixtures exist and are valid JSON
2. **Gate #2 - Cache Manifest**: Verifies DeepSeek cache hit manifests exist for osa + domedog
3. **Gate #3 - Runtime Inventory**: Ensures runtime inventory parity across all platforms
4. **Gate #4 - Cross-Platform**: Runs `cargo check --workspace` to ensure build passes
5. **Gate #5 - Watchdog**: Validates osa watchdog socket read successful
6. **Gate #6 - Caller Inventory**: Checks caller inventory documentation exists (precondition check)

### Exit Codes

- `0`: All critical gates passing
- `1`: Some critical gates failing

### Integration with CI/CD

```yaml
# Example GitHub Actions
- name: Validate Proof Gates
  run: cargo run --release --bin proof-gate-tracker
```

## Platform Matrix Tests

Cross-platform smoke tests are located in `tests/platform-matrix.rs`.

### Usage

```bash
# Run all platform matrix tests
cargo test --test platform-matrix

# Run with output
cargo test --test platform-matrix -- --nocapture

# Run specific test
cargo test --test platform-matrix all_platforms_validate_core_features -- --nocapture
```

### Tests Included

- `all_platforms_validate_core_features`: Validates all platforms (FreeBSD/Linux) have valid manifests
- `freebsd_specific_tests`: FreeBSD-specific validations (osa)
- `linux_specific_tests`: Linux-specific validations (domedog, debby)
- `cache_economics_parity`: Verifies cache hit rate consistency across platforms

## Multiagent Workflow Tools

### Agent Handoff Protocol

See `doc/<FEATURE>-HANDOFF.md` for the standardized handoff protocol used between agents.

### Handoff Template

```json
{
  "agent_from": "agent_name",
  "agent_to": "agent_name",
  "focus_area": "brief description",
  "proof_gates_pending": ["gate-1", "gate-2"],
  "known_limitations": ["limitation 1"],
  "next_steps": ["step 1", "step 2"],
  "context_files": ["file1.rs", "file2.md"],
  "test_evidence": ["manifests/file1.json"]
}
```

### Handoff Checklist

- [ ] All tests pass (`cargo test --workspace`)
- [ ] Relevant proof gates documented
- [ ] Cross-platform validation recorded
- [ ] Next agent's entry point marked
- [ ] Handoff entry added to `doc/<FEATURE>-HANDOFF.md`