Pre-flight Checks

Failure prevention checks that run before task execution to catch potential issues early.

What are Pre-flight Checks?

Pre-flight checks run automatically before task execution to verify that your environment and workspace are properly configured. These checks catch potential failures early, before they cause problems during task execution.

ℹ️

Checks have different severity levels: Warning (allows execution with notice) and Failed (blocks execution until resolved).

Available Checks

check_git_clean()

Warns if uncommitted changes exist in the repository. This prevents work on dirty branches where changes might be lost or conflict with new work.

Severity Level

Warning (does not block execution)

This is a warning-level check. Execution will proceed, but you will be notified of uncommitted changes.

Example

bash 
# Run checks before task
cco preflight --repo /path/to/repo --check git_clean

# Output example:
[WARNING] Uncommitted changes detected:
  M src/module.py
  ?? new_feature.py

check_dependencies_installed()

Verifies that required Python version and packages are installed. This ensures the orchestrator can run properly.

Severity Level

Failed (blocks execution)

If this check fails, task execution will be blocked until dependencies are installed.

Required Components

Component Requirement
Python Version 3.10 or higher
typer CLI framework
pydantic Data validation
httpx HTTP client for Ollama
pyyaml Config and trigger parsing

Example

bash 
# Run checks before task
cco preflight --repo /path/to/repo --check dependencies

# Example output on success:
[PASS] Python 3.12.3 detected
[PASS] typer installed
[PASS] pydantic installed
[PASS] httpx installed
[PASS] pyyaml installed

# Example output on failure:
[FAIL] Python 3.9 detected (requires 3.10+)
[FAIL] Missing dependency: typer

check_disk_space()

Ensures sufficient disk space is available for task execution and artifact storage.

Severity Thresholds

  • Failed: Less than 100MB free
  • Warning: Less than 1GB free
  • Pass: 1GB or more free

Example

bash 
# Check disk space
cco preflight --repo /path/to/repo --check disk_space

# Output example (pass):
[PASS] 15.2GB free disk space

# Output example (warning):
[WARN] Only 450MB free disk space
[WARN] Consider freeing up space before large operations

# Output example (failure):
[FAIL] Only 50MB free disk space
[FAIL] Execution blocked: insufficient disk space

check_memory_available()

Ensures sufficient RAM is available for task execution. Memory-intensive operations require adequate resources.

Severity Thresholds

  • Failed: Less than 256MB available
  • Warning: Less than 512MB available
  • Pass: 512MB or more available

Example

bash 
# Check available memory
cco preflight --repo /path/to/repo --check memory

# Output example (pass):
[PASS] 8.2GB available RAM

# Output example (warning):
[WARN] Only 380MB available RAM
[WARN] Consider closing other applications

# Output example (failure):
[FAIL] Only 120MB available RAM
[FAIL] Execution blocked: insufficient memory

check_context_valid()

Validates that .context/*.md files in the workspace are readable and properly formatted. This ensures that knowledge base files are accessible.

Severity Level

Failed (blocks execution)

If context files cannot be read or are malformed, task execution is blocked to prevent unpredictable behavior.

Validated Files

  • .context/architecture.md - Runtime architecture
  • .context/decisions.md - Architectural decisions
  • .context/known-issues.md - Known issues and mitigations
  • .context/deployment.md - Deployment notes

Example

bash 
# Check context files
cco preflight --repo /path/to/repo --check context_valid

# Output example (pass):
[PASS] 4 context files validated
[PASS] All .context/*.md files are readable

# Output example (failure):
[FAIL] Cannot read .context/architecture.md
[FAIL] Cannot read .context/decisions.md
[FAIL] Execution blocked: invalid context files

check_cross_refs_valid()

Validates file references in knowledge files. Checks that all referenced files exist and are accessible. This prevents broken links and missing includes.

Severity Level

Warning (does not block execution)

This is a warning-level check. Invalid references will be reported, but execution will proceed.

Example

bash 
# Check cross-references
cco preflight --repo /path/to/repo --check cross_refs

# Output example (pass):
[PASS] 12 cross-references validated
[PASS] All file references are valid

# Output example (warning):
[WARN] Broken reference: .context/decisions.md references missing file src/old_module.py
[WARN] Broken reference: .context/architecture.md references non-existent docs/api.md

CLI Integration

Pre-flight checks are integrated into the CCO CLI through the --preflight flag on relevant commands.

cco plan --preflight

Runs pre-flight checks before planning a task. This ensures your environment is ready before generating a plan.

bash 
cco plan --repo /path/to/repo --task "Implement user authentication" --preflight

cco task --preflight

Runs pre-flight checks before executing a task. This is the primary integration point for failure prevention.

bash 
cco task --repo /path/to/repo --task "Implement user authentication" --preflight

Running All Checks

To run all pre-flight checks explicitly:

bash 
cco preflight --repo /path/to/repo

Python API

Pre-flight checks can be used programmatically through the Python API.

PreFlightCheck Class

The PreFlightCheck class provides a Python interface for running checks:

python 
from pathlib import Path
from codified_orchestrator.failure_prevention import PreFlightCheck

# Initialize checker with workspace path
checker = PreFlightCheck(workspace=Path("/path/to/repo"))

# Run all checks
results = checker.run_all()

# Check individual results
for check_name, result in results.items():
    print(f"{check_name}: {result.status}")
    if result.message:
        print(f"  {result.message}")

preflight_check() Function

A convenience function for quick pre-flight validation:

python 
from pathlib import Path
from codified_orchestrator.failure_prevention import preflight_check

# Quick check - returns (all_passed: bool, results: dict)
all_passed, results = preflight_check(Path("/path/to/repo"))

if all_passed:
    print("All pre-flight checks passed!")
else:
    for check_name, result in results.items():
        if not result.passed:
            print(f"Failed: {check_name} - {result.message}")

Running Individual Checks

Run specific checks programmatically:

python 
from pathlib import Path
from codified_orchestrator.failure_prevention import PreFlightCheck

checker = PreFlightCheck(workspace=Path("/path/to/repo"))

# Run individual checks
git_result = checker.check_git_clean()
deps_result = checker.check_dependencies_installed()
disk_result = checker.check_disk_space()
memory_result = checker.check_memory_available()
context_result = checker.check_context_valid()
cross_refs_result = checker.check_cross_refs_valid()

# Print results
print(f"Git clean: {git_result.status}")
print(f"Dependencies: {deps_result.status}")
print(f"Disk space: {disk_result.status}")
print(f"Memory: {memory_result.status}")
print(f"Context valid: {context_result.status}")
print(f"Cross refs: {cross_refs_result.status}")
↑↓ Navigate Enter Select Esc Close