From 68083be6d08a49c8f15a99017315478a1b6646f9 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Wed, 14 Oct 2026 03:18:06 +0000 Subject: [PATCH 1/2] docs: Read the shared contribution policy Remove setup, check, budget, and commit rules that CONTRIBUTING.md and docs/developer/AI_POLICY.md already state, and say when to read those files instead. Claude-Session: https://claude.ai/code/session_01XGMpowzJwwgyHMEd63ijDe --- AGENTS.md | 52 ++++++++++++++++++++-------------------------------- 1 file changed, 20 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d6b72f90..16378c80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,27 +28,19 @@ 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 +Before setting up an environment or choosing checks, read the setup and check +list in `CONTRIBUTING.md`. Use the existing virtual environment when available. +Pick checks by what changed: + +- Runtime changes: affected pytest tests, Ruff, and mypy. +- 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,8 +53,7 @@ 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, +Respect the review-line budgets in `CONTRIBUTING.md`. New dependencies, public API signature or return-shape changes, and lint suppressions require user authorization; an explicit request can already provide that authorization. @@ -86,18 +77,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. From 4acc2d299780c21ca64544e0eacda087c746c861 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Mon, 26 Oct 2026 11:20:48 -0500 Subject: [PATCH 2/2] docs: Preserve project-specific agent checks Keep concise setup, verification commands and the enforced line budget in AGENTS.md. CONTRIBUTING.md documents review procedure, not these repository-specific checks. --- AGENTS.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 16378c80..2d8661e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,11 +28,14 @@ contains offline verification utilities. ## Development and verification -Before setting up an environment or choosing checks, read the setup and check -list in `CONTRIBUTING.md`. Use the existing virtual environment when available. +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, Ruff, and mypy. +- 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. @@ -53,9 +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. -Respect the review-line budgets in `CONTRIBUTING.md`. 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