diff --git a/AGENTS.md b/AGENTS.md index d6b72f9..2d8661e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,27 +28,22 @@ contains offline verification utilities. ## Development and verification -Use the existing virtual environment when available. Python 3.10 is the minimum; -the supported range is Python 3.10 through 3.15. Install development -dependencies only when needed: -`python -m pip install -e '.[dev]'`. Run the CLI with `codex32 --help`. - -Choose checks according to the changed behavior: - -- Runtime changes: run affected pytest tests, Ruff lint and formatting checks, - and `python -m mypy src/codex32` when types or source code change. -- Changes spanning modules or security boundaries: run `python -m pytest -q` - and `python -O -m pytest -q`; use the relevant differential tools for changes - to correction or wallet derivation. -- Packaging or release changes: run `python -m build` and - `python -m twine check dist/*` in addition to affected checks. -- Documentation or agent-configuration changes: inspect the diff, check links - and configuration syntax as applicable; do not run application tests solely - for prose or instruction edits. - -Use `python -m ruff check .` and `python -m ruff format --check .` for Python -style checks. Once applicable checks pass, repeat or broaden them only for a new -change, failure, or unresolved concern. Report checks that could not run and +Read `CONTRIBUTING.md` for the contribution workflow. Use Python 3.10–3.15 +and an existing virtual environment where available; otherwise install +development dependencies with `python -m pip install -e '.[dev]'`. +Pick checks by what changed: + +- Runtime changes: affected pytest tests, `python -m ruff check .`, + `python -m ruff format --check .`, and `python -m mypy src/codex32` + when changing types or source. +- Changes spanning modules or security boundaries: the full suite, also under + `python -O`, plus the differential tools for correction or wallet derivation. +- Packaging or release changes: the build and `twine check` steps as well. +- Documentation or agent-configuration changes: inspect the diff and check links + and syntax; do not run application tests for prose edits alone. + +Once applicable checks pass, repeat or broaden them only for a new change, +failure, or unresolved concern. Report checks that could not run and pre-existing failures accurately; do not claim unverified success. ## Reviewability and style @@ -61,10 +56,10 @@ avoid comments or tests that restate the implementation. Add or update concise docstrings when changing public behavior. Write codex32 in lowercase except when referring to the Codex32 Book. -Keep the installed package below 5,200 logical review lines, as enforced by the -existing test. New dependencies, public API signature or return-shape changes, -and lint suppressions require user authorization; an explicit request can -already provide that authorization. +Keep the installed package below 5,200 logical review lines, enforced by +`test_production_size_budgets_are_enforced`. New dependencies, public API +signature or return-shape changes, and lint suppressions require user +authorization; an explicit request can already provide that authorization. Use pytest and Hypothesis for meaningful behavioral coverage. Preserve external vectors, negative cases, and regressions for changed behavior. Prefer one clear @@ -86,18 +81,15 @@ Resolve scope questions from the changed code and the invariants first. Ask only if a material security decision remains unclear; identify the decision rather than stopping on general uncertainty. Ask before running a recommended security review. -Before acting on a pull request, read `CONTRIBUTING.md` and -`docs/developer/AI_POLICY.md` from its current target branch. Follow that merged -contribution policy when the topic branch contains an older version. AI may -write PR descriptions and review replies under the tool-neutral policy. +Before committing, opening a pull request, or writing an issue, pull request, +or review comment, read `CONTRIBUTING.md` and `docs/developer/AI_POLICY.md` +from the pull request's current target branch; they decide authorship, commit +messages, and who publishes. Follow that merged policy when the topic branch +contains an older version. AI may write PR descriptions and review replies under +the tool-neutral policy. Follow `SECURITY.md` for private vulnerability reporting. Local edits, checks, and atomic commits are allowed. Publish only within the user's authorized scope; permission to use AI does not itself authorize contacting others. Never claim independent human authorship, commit to master, or push to an open pull request branch without explicit user direction. - -When asked to commit, keep commits focused and independently passing unless the -user explicitly requests a combined commit. Use an imperative subject of at -most 50 characters, followed by rationale, security implications when relevant, -and validation. Use `refs #123` or `fixes #123` when applicable.