# Repository Guidelines ({project_name})
{project_description}
## Non-Negotiables
- CI gate: `make ci` MUST pass before claiming completion, committing, or merging.
- Source docs: every new/changed source file MUST start with a module docstring that states:
- what the file is responsible for
- what it explicitly does NOT handle
- any invariants/assumptions callers must respect
- Tests: all new/changed behavior must be covered (success + failure modes). Prefer tests near the code.
- Type safety: use strict, safe typing and type hints throughout.
- Secrets: never commit or print secrets; redact sensitive output before recording in documentation.
## Repository Map
{repository_map}
## Build, Test, and CI
The Makefile is the contract; keep these targets working:
- `make ci`: local CI gate (install → format → type-check → lint → build → test). Do not remove `install`.
- `make install`: install dependencies via `uv sync`.
- `make test`: run all tests with `uv run pytest`.
- `make lint`: `uv run ruff check --fix`
- `make format`: `uv run ruff format`
- `make type-check`: `uv run ty check`
- `make update`: update all deps to latest stable versions.
- `make clean`: remove lock files, node_modules, log files, etc.
Useful iteration commands (not a substitute for `make ci`):
- `uv run pytest tests/`
- `uv run python -m {module_name}`
- `uv run ruff check .`
## Python Conventions
- Use strict, safe typing and type hints; Pydantic where valuable.
- Use astral `uv` and `pyproject.toml` for dependency management.
- Lint: `uv run ruff check --fix`
- Format: `uv run ruff format`
- Type check: `uv run ty check`
- Keep modules/files focused; split large files rather than growing grab-bags.
- Individual source files SHOULD remain under ~400 LOC.
- Files exceeding ~700 LOC REQUIRE explicit justification explaining why cohesion is still intact.
- Files exceeding ~1,000 LOC are presumed to be mis-scoped and MUST be split unless proven otherwise.
## Testing
- Unit tests: colocate with implementation or in `tests/` directory.
- Integration tests: use `tests/` directory when cross-module behavior is the subject.
- Temp dirs: tests should use isolated temp directories.
- Use pytest fixtures for test setup and teardown.
## Workflow Contracts
- Task tracking: use the project's task system for active work.
- Task ordering: top of queue runs first.
- Planning: write plans to designated cache directory (do not print inline).
- Completion: signal completion through proper channels for supervisor flow.
## Configuration
Config precedence (highest to lowest):
1. CLI flags
2. Project config files
3. Global config files
4. Schema defaults
## Git Hygiene
- Commit message: `{id_prefix}-####: <short summary>` (task id + summary).
- Do not commit if `make ci` is failing.
- Prefer local CI over remote CI.
## Documentation Maintenance
- Schema changes: update code, regenerate schemas, and keep docs aligned.
- CLI changes: update help text/examples and keep CLI documentation aligned.
- Task field changes: update task documentation.
## Troubleshooting
- CI failing: run `make ci`; common checks are `uv run ruff check`, `uv run ty check`, `uv run pytest`.
- Dependency issues: try `make clean && make install` to refresh the environment.
- Type errors: ensure all functions have proper type annotations.
---
*Generated by Ralph v{version} - {timestamp}*
*Template version: {template_version}*