From 418fefdeef6934381d6e2691777832e103923c34 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 23 Sep 2026 17:58:49 +0000 Subject: [PATCH] Align repository policies with current standards --- AGENTS.md | 34 +------------- docs/development.md | 2 + docs/policy/agents.md | 91 ++++++++++++++++++++++++++++++++++++ docs/policy/documentation.md | 5 +- docs/policy/release.md | 10 +++- 5 files changed, 106 insertions(+), 36 deletions(-) create mode 100644 docs/policy/agents.md diff --git a/AGENTS.md b/AGENTS.md index 68a03c4..b9989e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,5 @@ Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide. -## Implementation Discipline - -Simplify the mechanism, not the user's choices. - -**Keep implementation machinery proportionate.** Use straightforward, -idiomatic code and introduce only the machinery needed to support the requested -behavior and flexibility. Optimize for conceptual simplicity and -maintainability, not for the fewest lines, fewest options, or narrowest product -surface. - -**Do not invent restrictions.** Do not reject, prohibit, constrain, cap, -harden, or otherwise narrow behavior unless required by the user, an explicit -repository contract, or an unavoidable correctness constraint. Preserve -operator and caller choice where policy has not been established. If an -additional restriction appears advisable, present it as a decision rather than -silently implementing it. - -A correctness constraint must follow from the requested behavior or an -established invariant, not from the convenience of the chosen implementation. -Explain the specific failure it prevents and why a less restrictive -implementation cannot satisfy the contract. - -**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. Existing -explicit contracts remain authoritative; changing or weakening one requires a -deliberate decision rather than being inferred from this principle. - -Agent-authored plans, tests, documentation, and prior implementations are not -evidence that an additional restriction was deliberately approved. Identify the -authorizing requirement or decision; when that authority is unclear, surface -the ambiguity rather than treating repetition as approval. +Review and follow `docs/policy/agents.md` before recommending, planning, or +implementing any changes to this repository. diff --git a/docs/development.md b/docs/development.md index f278a78..c552b2d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -8,6 +8,8 @@ public behavior. ## Initial orientation 1. Inspect the working tree and preserve unrelated changes. + Agents must read and follow the [agent policy](policy/agents.md) before + recommending, planning, or implementing changes. 2. Read the architecture policy for code or design work. 3. Read the policy, contract, and internal documents applicable to the task. 4. Inspect the relevant implementation and behavioral tests before changing them. diff --git a/docs/policy/agents.md b/docs/policy/agents.md new file mode 100644 index 0000000..4d83d5a --- /dev/null +++ b/docs/policy/agents.md @@ -0,0 +1,91 @@ +# Agent Policy + +**Base Policy Version:** 1.1 + +**Last Updated**: 2026-09-23 + +## Purpose + +Agents working in this repository must read and adhere to the following house rules. + +## Implementation Discipline + +**KEY PRINCIPLES:** Write the simplest idiomatic code that satisfies the user's +request. Do not implicitly strengthen requirements, restrictions, or guarantees +beyond what the user actually requested. + +Simplify the mechanism, not the user's choices. + +**Keep implementation machinery proportionate.** Use straightforward, +idiomatic code and introduce only the machinery needed to support the requested +behavior and flexibility. Optimize for conceptual simplicity and +maintainability, not for the fewest lines, fewest options, or narrowest product +surface. + +**Do not invent restrictions.** Do not reject, prohibit, constrain, cap, +harden, or otherwise narrow behavior unless required by the user, an explicit +repository contract, or an unavoidable correctness constraint. Preserve +operator and caller choice where policy has not been established. If an +additional restriction appears advisable, present it as a decision rather than +silently implementing it. + +A correctness constraint must follow from the requested behavior or an +established invariant, not from the convenience of the chosen implementation. +Explain the specific failure it prevents and why a less restrictive +implementation cannot satisfy the contract. + +**Do not invent guarantees.** Do not strengthen public contracts, guarantees, +or invariants beyond those expressly requested by the user. + +**Use the standard library.** For example: in almost every case, the best +approach to copying files is to use the standard library. Writing custom code to +implement power-loss protection at the application level, or to guard against +bad actors with privileged and concurrent access to the host's filesystem, +is wasteful, unnecessary, and not idiomatic. Stick to the simple, standard, and +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. Existing +explicit contracts remain authoritative; changing or weakening one requires a +deliberate decision rather than being inferred from this principle. + +Agent-authored plans, tests, documentation, and prior implementations are not +evidence that an additional restriction was deliberately approved. Identify the +authorizing requirement or decision; when that authority is unclear, surface +the ambiguity rather than treating repetition as approval. + +## 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. diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index b439a3a..d24bd77 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,8 +1,8 @@ # Documentation Policy -**Base Policy Version:** 1.0 +**Base Policy Version:** 1.1 -**Last Updated:** 2026-09-06 +**Last Updated:** 2026-09-23 ## Purpose @@ -59,6 +59,7 @@ handling, not secret values. | Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example | | Contributor entry point | `docs/development.md` | Reading guide and actual baseline validation commands | | Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries | +| Agent rules | `docs/policy/agents.md` | Implementation discipline, proportionality, rules against inventing contracts, and local commit authorization; not application contracts or architecture | | Documentation rules | `docs/policy/documentation.md` | Ownership and document lifecycle | | Testing rules | `docs/policy/testing.md` | Risk-based sufficiency, test boundaries, and maintenance principles | | Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions | diff --git a/docs/policy/release.md b/docs/policy/release.md index 449b89e..d8c35da 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,8 +1,8 @@ # Release Policy -**Base Policy Version:** 0.1.0 +**Base Policy Version:** 1.0 -**Last Updated:** 2026-09-12 +**Last Updated:** 2026-09-23 ## Purpose @@ -234,6 +234,12 @@ restating or redefining its requirements. ## Policy Exceptions +Any exception to this policy must be explicitly documented in this section, +including the repository constraint requiring it, its rationale, scope, and +compensating controls. Customizing release mechanics must not silently weaken +the policy's integrity, validation, documentation, verification, or immutability +requirements. + For v0.1.1 only, the maintainer approved renaming the reserved `_configkit` key to `configkit` as an error-correcting point release because there are no current consumers. This intentionally changes the v0.1.0 configuration contract without a