Contributing

Contributing

Scholion is a small, vibe-coded experiment, so expect rough edges and say so in issues when you hit one. The authoritative guide is CONTRIBUTING.md.

Setup

• Rust is pinned in rust-toolchain.toml (1.97.1); rustup picks it up. Don't bump it in an unrelated change.
• Tests need Postgres. With nothing set, the test helper downloads an embedded user-space Postgres on first run. To use your own server, set AV_TEST_DATABASE_URL=postgres://user:pass@127.0.0.1:5432/postgres; each test creates its own database there.
• Qdrant tests skip silently unless AV_TEST_QDRANT_URL (gRPC, e.g. http://127.0.0.1:6334) is set, so a green run does not prove the Qdrant code works.

Before you open a pull request

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

All three must pass; CI runs the same on every pull request, against Postgres and Qdrant service containers. For changes to the stack or the CLI's end-to-end flow, also run scripts/smoke.sh.

Useful filters:

cargo test -p scholion-daemon --test api submit_
cargo build --release -p scholion-cli          # -> target/release/scholion and av

How changes are made

• Tests first. Write the failing test, then the code. Daemon behaviour is tested through the HTTP API (crates/scholion-daemon/tests/api.rs); many agents at once in tests/swarm.rs; routing in tests/routing.rs; MCP in tests/mcp.rs; context-pack output against golden files in crates/scholion-pack/tests/golden/.
• Migrations live in crates/scholion-store/migrations/, numbered 000N_*.sql. Take the next number after main's highest. A merged migration is never edited, not even a comment: databases store its checksum, and tests/migrations_frozen.rs pins each file's hash (add a line for a new migration).
• One change per pull request, branched from main.
• Larger features start as a plan in docs/superpowers/plans/. Older plans and the design spec use the project's earlier name (crates av-*).
• Agent-facing text (pack output, MCP tool descriptions, hook messages) says av, not scholion.

Invariants worth not breaking

• Record summaries are at most 200 characters, and records are append-only.
• submit and handoff are refused without an intent plus at least one decision, attempt, note or handoff record.
• main advances only through merge (and revert).
• The daemon never runs repository commands.
• Carrying an approval fails closed: when in doubt, ask for a fresh review.
• Everything in compose binds to 127.0.0.1.

Security issues

Report them privately through a GitHub security advisory, not in a public issue. See Security.