colibri/tools

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

# 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

# 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

# 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

{
  "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