Contributing and Protocols

Contributing and Protocols

The rules are in CONTRIBUTING.md and, for AI sessions, CLAUDE.md. This page summarises them.

Workflow

1. Issue first, from the template, with done criteria. Milestones are GitHub milestones M6 to M11; work is on the project board.
2. Branch feat/<issue#>-<slug> (or docs/, chore/, release/). One session per working checkout; a second concurrent session works in its own git worktree.
3. Conventional Commits. Docs change in the same PR as the code: README, ARCHITECTURE and its generated diagrams, an ADR for any architectural or high-impact change, CHANGELOG under [Unreleased], docstrings for public APIs.
4. Draft PR from the template with Closes #N, plan versus done, test evidence, the ledger ids and the sweep pattern. Checks must be green; merging is a human action.
5. Releases: patch for fix-only or additive changes, minor when configs, CLI flags, state fields or schemas change. scripts/release_notes.py --cut X.Y.Z cuts the changelog, the package version is bumped in pyproject.toml and scio/__init__.py (a test keeps them equal to the newest changelog section), a PR lands it, then the vX.Y.Z tag on the merge commit triggers the release workflow.

The local CI chain

Run it before every push, in one shell command starting with set -o pipefail:

uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest && uv run python scripts/check_docs.py && uv run python -m evals.runner --suite regression --provider fake --trials 5 --min-pass-pow-k 1.0

Tests, lint and types are ground truth. Do not weaken a check to make it pass; fix the code or record a ledger entry explaining the exception.

Continuous improvement protocols

• Issue ledger (docs/ISSUE_LEDGER.md): the moment a problem appears (a failed command, a failing test, a wrong assumption, an environment quirk, a rejected push) it gets the next I-NNN entry. When resolved, the entry gains the root cause, the fix, the sweep and the status. Nothing is left out for being small.
• Milestone retrospectives (docs/LESSONS_LEARNED.md): read end to end before starting a milestone, saying which lessons shape the plan; at the end, add a section with what succeeded, what failed, and actions that are files, tests, rules or ledger ids, never intentions.
• Systemic sweeps: a bug fix has three parts: the root cause, a search of the whole codebase for the same construct (the grep is recorded in the ledger entry), and a guard against recurrence (a test, a lint rule, a docs check or a rule). Every instance found is fixed.

Engineering rules worth knowing before the first edit

• Offline by default (SCIO_PROVIDER_OVERRIDE=fake); live calls only under tests/live behind SCIO_RUN_LIVE_TESTS=1 or in explicit eval runs. Live runs cost money: one trial, read the cost by role, then scale.
• Model IDs live only in configs/models.yaml; the docs check fails on a model ID in code.
• Files are written with LF endings; any text containing a backslash (Windows paths, regexes, escapes) goes through file tools, never a shell-embedded script.
• Dependencies go in pyproject.toml with uv sync, never ad hoc installs. Behind a corporate proxy, UV_SYSTEM_CERTS=1.
• One writer: never two agents editing code concurrently; parallel work is read-only.
• A model's structured output reports; the plan decides. Every output that drives control flow gets a normaliser, and every loop needs a cap on the passing path as well as the failing one.