flowchart TD
    subgraph ControlPlane["CLI & Orchestration (scripts/run_evaluation.py)"]
        CLI["CLI Runner"] --> Runner["EvaluationRunner"]
        CLI --> Loop["AgentExecutionLoop"]
    end

    subgraph AgentLayer["Autonomous Agent & Planning (src/agent/)"]
        Loop --> Planner["SystematicSWEPlanner / LLMPlanner"]
        Planner -->|AgentAction| Loop
        Loop -->|call_tool| Client["MCPClient (Async stdio)"]
    end

    subgraph ProtocolBoundary["Model Context Protocol Boundary"]
        Client <==>|Anonymous OS Pipes (stdio JSON-RPC)| Server["MCPServer (Subprocess)"]
    end

    subgraph ToolSurface["Sandboxed Tool Surface (src/mcp_server/)"]
        Server --> T1["list_files"]
        Server --> T2["read_file"]
        Server --> T3["search_code"]
        Server --> T4["apply_patch"]
        Server --> T5["get_git_diff"]
        Server --> T6["run_tests"]
        Server --> T7["get_test_output"]
        Server --> T8["get_repository_status"]
    end

    subgraph SecurityBoundary["Security & Anti-Cheat Sandbox (src/mcp_server/security/)"]
        T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 --> Sandbox["SecurityPolicy Engine"]
        Sandbox --> Guard1["Path Traversal Containment"]
        Sandbox --> Guard2["Anti-Cheat (Hidden Tests Isolated)"]
        Sandbox --> Guard3["Command Whitelisting & Injection Defense"]
    end

    subgraph TaskWorkspaces["Ephemeral Sandboxes (tasks/)"]
        Guard1 & Guard2 & Guard3 --> TargetRepo["Ephemeral Workspace (.git)"]
    end

    subgraph Evaluator["Deterministic Evaluator Engine (src/evaluator/)"]
        TargetRepo --> Verifier["TaskVerifier"]
        Verifier --> ShaCheck["SHA-256 Digest Tamper Check"]
        Verifier --> PublicRun["Public Test Execution"]
        Verifier --> HiddenRun["Privileged Hidden Test Suite"]
        Verifier --> DiffAnalysis["Git Diff & Line Metrics"]
        ShaCheck & PublicRun & HiddenRun & DiffAnalysis --> Scorer["ScoringEngine (100 Pt Model)"]
        Scorer --> Artifacts["Telemetry Artifacts (results/eval_*.json, .md)"]
    end

# Clone the repository
git clone https://github.com/kirubesh/CodeForgeX.git
cd CodeForgeX

# Install virtual environment and dependencies using uv or pip
pip install -e .

pytest -v

# Run the entire benchmark suite in golden reference mode
python scripts/run_evaluation.py --all

# Run a specific task in autonomous agent mode (MCP stdio tool-calling loop)
python scripts/run_evaluation.py --task bug_fix_001 --mode agent-systematic

# Filter benchmarks by category or difficulty
python scripts/run_evaluation.py --category algorithm
python scripts/run_evaluation.py --difficulty medium

# Build the security-hardened container
docker build -t codeforge-x:latest .

# Run full evaluation across all tasks inside Docker
docker run --rm codeforge-x:latest --evaluate-all

# Or run using Docker Compose with cgroups limits and tmpfs in-memory sandboxes
docker compose up codeforge-eval