diff --git a/docs/policy/agents.md b/docs/policy/agents.md index 5b7c03b..4927f2a 100644 --- a/docs/policy/agents.md +++ b/docs/policy/agents.md @@ -1,6 +1,6 @@ # Agent Policy -**Base Policy Version:** 1.0 +**Base Policy Version:** 1.1 **Last Updated**: 2026-09-23 @@ -50,3 +50,38 @@ idiomatic approach unless another path is expressly requested by the user. **An implementation detail is not repository policy.** Tests and documentation must not elevate incidental behavior into a durable guarantee or restriction unless that behavior was expressly selected as part of the contract. + +## Git Commit Policy + +By default, create a commit after completing each coherent unit of work, using a +concise, plain-English message describing what changed. This policy is standing +authorization to create those local commits; a separate user request is not +required. An explicit user instruction to leave work uncommitted takes precedence. + +A unit of work is a focused, reviewable outcome, including its relevant tests and +documentation. Do not commit after every intermediate edit or create empty commits. +Complete the appropriate validation before committing. If work is incomplete or +validation is blocked, report that state rather than presenting it as completed. + +Before committing: + +1. Run `git status --short` and review the relevant diff, including any staged + changes. Identify changes that predate the current unit of work. +2. Exclude secrets, local environment files, generated junk, and unrelated changes. +3. Stage only the files or hunks belonging to the completed unit. Use `git add .` + only when every included change belongs to that unit. Do not disturb unrelated + staged or unstaged work. +4. Review `git diff --staged` and run appropriate checks for the change. Do not + repeat checks already passed for unchanged content merely to create a commit. +5. Review `git log --oneline -n 10` and use + `git commit -m ""`. +6. Report the commit identifier and any remaining uncommitted work. + +If the unit cannot be safely separated from pre-existing work, leave it uncommitted +and explain the overlap rather than silently including that work. If a commit +fails, preserve the changes and report the failure; do not bypass hooks. + +Default commit authorization does not authorize pushing, publishing, amending, +resetting, reverting, or rewriting history. Those actions require a separate user +instruction. Do not use `git commit -a` or `git commit --no-verify` to bypass the +staging and validation discipline above.