# Contributing
Condor keeps durable contributor guidance in this file, the root README, the
`Justfile`, and the owning source. The ignored `docs/` directory is a local
notebook for design exploration and is not required by a clean clone, package,
build, test, example, catalog, or release workflow.
## Working boundaries
Start at the nearest `AGENTS.md` before changing a directory. It gives the
local mission, allowed scope, non-goals, narrow validation route, related
source, and escalation boundary. Root `AGENTS.md` supplies repository-wide
consumer, dependency, and safety rules; a local guide can add constraints but
cannot relax them.
- Runtime algorithms live in their owning crate under `crates/`; the root
`src/` facade only curates the public `condor` API and its deliberate
root-owned contracts.
- Root `tests/` and `examples/` exercise the published consumer surface.
Runtime behavior belongs beside its owner, not in another root target.
- `condor-harness` owns shared correctness corpora, fixture provenance,
conformance, and opt-in oracle evidence. `condor-bench` owns benchmark lanes,
captures, reports, and catalog data. `condor-lab` only presents bench-owned
catalog data.
- Generated evidence belongs below ignored `target/condor/`; do not commit it.
## Repository ownership
Runtime implementations belong to their domain crates under `crates/`.
Shared fixture loaders and correctness corpora belong to `condor-harness`;
benchmarks, reports, and catalogs belong to `condor-bench`.
Algorithm candidates are ordinary private modules beside their mature family
implementations. Keep them unreexported until an explicit promotion decision,
and exercise them through that family's ordinary source validation route. Use
harness conformance only when the mature family already needs corpus-backed
evidence; do not add an experiment workspace package, lane manifest, fixture,
or parallel test route.
Each retained candidate records its stable ID, next implementation step, and a
short source-local contract: the hypothesis, behavior that must not regress,
the owning validation/evidence route, and the evidence required before a
promotion decision. Keep rejected approaches only when they prevent a known
wrong implementation path. A candidate whose intent no longer warrants a
private module should be deleted rather than preserved in a separate planning
catalog.
## Local dependency contract
`Cargo.toml` manifests are the source of truth for package edges. The checked
architecture guard enforces this allowed local dependency graph; external
registry dependencies are outside this rule.
| `condor-for-games` facade | core, geometry, grid, navmesh |
| core | none |
| geometry and grid | core |
| navmesh | core, geometry |
| `condor-harness` | core, geometry, grid, navmesh |
| `condor-bench` | harness, core, geometry, grid, navmesh |
| `condor-tui` | none (shared Ratatui chrome leaf) |
| `condor-lab` | bench, condor-tui |
| `condor-path-lab` | bench, geometry, grid, navmesh, condor-tui |
The rule applies to normal, build, development, and target-specific edges. The
only checked development exceptions are the harness and bench black-box
consumer tests that depend on the root facade; their normal and build edges
must still point directly at owner crates. Lab's normal dependency on bench is
required so it can render the read-only developer catalog without reaching the
facade or a domain crate.
Do not add an upward or sideways edge to make a change compile. A new workspace
package needs an explicit role in `scripts/architecture-check.py` before it is
added to the workspace. The root package contains a facade, not path-included
owner sources; its published archive resolves versioned domain dependencies.
Use `just architecture-check-package <package>` while migrating one owner, and
`just architecture-check` at a repository validation boundary. The latter also
checks that the harness copies of the root public polygon packs remain
byte-identical.
## Validation
Use the narrow checked-in `Justfile` recipe for the owner you changed. Normal
edit-loop validation is `just format-check`, then the owner test and Clippy
route. For explicit integration targets, use `just test-fast <target>` and
`just clippy-target <target>`; focused any-angle work instead uses
`just test-any-angle-case <filter>`. Root consumer-surface work uses
`just test-product-surface`, `just clippy-target product_surface`, and, when
feature exposure changes, `just check-root-lib-all-features`.
Exact oracle, stress, full-suite, and benchmark measurement routes are opt-in.
Do not substitute a broad raw Cargo command when a narrow checked-in route
exists; see `just --list` for named commands.
Before release or final migration handoff, run the repository's required
formatting and full Clippy gates, the relevant owner tests, doctests, and the
architecture check. Release readiness also requires reviewing the generated
benchmark scorecard and stability matrix, confirming public examples, and
regenerating the release-readiness catalog below `target/condor/`.
## Dependencies and security
Prefer small dependency updates and commit `Cargo.lock` whenever resolution
changes. Use `cargo update -p <crate>` for a targeted advisory or compatibility
update. CI uses `cargo audit --deny warnings` for RustSec advisories. If an
advisory cannot be fixed immediately, document the reason in the change and
prefer a narrow, expiring ignore tied to a tracking issue over a permanent
suppression.