feat: add CTF swarm foundation

[ryu7eroo]

No description provided.

[Copilot]

Pull request overview

Introduces the initial “CTF Swarm” foundation package, including the core async scheduler orchestration, shared data models, and a basic verification boundary, along with a smoke test and updated project metadata/docs.

Changes:

• Added core orchestration (Scheduler) with round progression, candidate verification, and global cancellation events.
• Added foundational domain models (Challenge, Evidence, Candidate, TaskState) plus Agent protocol/context and Blackboard.
• Added packaging/test scaffolding (pyproject.toml, tests/test_scheduler.py) and replaced the README with CTF Swarm documentation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
ctf_swarm/agent.py	Defines agent protocol and the context passed into solver workers.
ctf_swarm/blackboard.py	Stores/merges evidence and derives “dead ends” across rounds.
ctf_swarm/models.py	Adds core data structures and enums for rounds/events/state.
ctf_swarm/scheduler.py	Implements async scheduling, verification, and global cancellation event emission.
ctf_swarm/verifier.py	Adds a minimal verification policy boundary for candidates.
ctf_swarm/__init__.py	Exposes the package’s main public symbols.
tests/test_scheduler.py	Adds a basic test for “first verified candidate wins + cancellation.”
pyproject.toml	Adds minimal project metadata and pytest config.
README.md	Documents the CTF Swarm architecture and dev workflow.

Suppressed comments (3)

ctf_swarm/scheduler.py:38

• run_one is annotated as returning Candidate | object | None, but Agent.solve is specified to return Candidate | Evidence | None. Using object here defeats type checking and makes it easier for non-Evidence values to slip into Blackboard handling.

        async def run_one(agent: Agent) -> Candidate | object | None:

ctf_swarm/scheduler.py:61

• Non-candidate results are passed directly to Blackboard.add_evidence, but Blackboard expects an Evidence instance. If an agent accidentally returns an unsupported non-None value, this will raise at runtime. Guard this with an Evidence type check (and optionally record a REJECTED event for unexpected return types).

                elif result is not None:
                    board.add_evidence(result)

tests/test_scheduler.py:38

• Compare EventTypes directly rather than comparing .value strings; this keeps the test resilient to enum value changes and makes failures clearer.

        assert any(e.type.value == "global_cancel" for e in scheduler.events)

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.