diff --git a/docs/policy/agents.md b/docs/policy/agents.md new file mode 100644 index 0000000..ddbc40f --- /dev/null +++ b/docs/policy/agents.md @@ -0,0 +1,52 @@ +# Agent Policy + +**Base Policy Version:** 1.0 + +**Last Updated**: 2026-09-06 + +## Base Policy Template + +This document is the base template for the canonical house rules that agents must follow while working in this repository. Repositories that implement this policy should: + +1. Review the policy, remove any rules that must not apply to the current project, and add any additional rules that are required by the current project; +2. Update the `Last Updated` field to the current date; and +3. Remove this heading (`Base Policy Template`) and the associated text. + +Most projects will not require any revisions to the substantive policy rules as written below. + +## 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. + +**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. + +**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. diff --git a/docs/policy/release.md b/docs/policy/release.md index 485203e..f673814 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -129,30 +129,15 @@ The required gates are: - dependency or module hygiene appropriate to the language and ecosystem; - the complete deterministic, offline default test suite; -- race, concurrency, or equivalent safety checks where the implementation can - be meaningfully checked for those risks; - static analysis and linting used by the repository; -- production builds for every supported target that can be built in the - release environment; - formatting and whitespace checks; - validation of maintained examples, configuration, schemas, generated sources, and documentation commands where applicable; - review of changed local documentation links; - removal of obsolute roadmap documents under `docs/roadmap/` that describe - completed work included in the release; + completed work included in the release; and - review for unintended files, generated output, credentials, private data, - and unrelated changes; and -- any additional security, compatibility, migration, packaging, or platform - checks required by the product. - -Unavailable tooling or an inapplicable check must be addressed explicitly in -the adopted policy or release procedure; it must not disappear silently from -the candidate gates. - -Run the complete checker while preparing the candidate. Commit the release -note and all associated code, tests, documentation, and configuration, then -run the complete checker again against the exact commit intended for release. -Do not publish a release from uncommitted or unvalidated content. + and unrelated changes. ## Publication Guards diff --git a/docs/policy/testing.md b/docs/policy/testing.md index eb5cccf..34bbcc0 100644 --- a/docs/policy/testing.md +++ b/docs/policy/testing.md @@ -6,7 +6,7 @@ ## Base Policy Template -This document is the base template for the canonical testing policy,. Repositories that implement this policy should: +This document is the base template for the canonical testing policy. Repositories that implement this policy should: 1. Review the policy, remove any rules that must not apply to the current project, and add any additional rules that are required by the current project; 2. Update the `Last Updated` field to the current date; and @@ -69,7 +69,7 @@ Control clocks, randomness, environment variables, and other process-global or m ## What deserves tests -Prioritize tests for: +To the extent the following features are present in the application, prioritize tests for: 1. Public and package-level contracts. 2. Domain rules and important invariants. @@ -99,7 +99,7 @@ Do not force all behavior through oversized end-to-end tests. Do not test every ## Test behavior, not implementation -A test should protect a decision, contract, or invariant—not memorialize the current implementation. +A test should protect a decision, contract, or invariant. A test must not memorialize the current implementation. Before adding or retaining a test, ask: @@ -116,7 +116,7 @@ A test is suspect when its main purpose is to detect that someone: Refactoring should normally require no test edits unless the refactored structure is itself part of the contract. -A test can be factually correct and still have negative value. Accurately describing current behavior is not enough; the protected behavior must be important enough to justify the future friction. +A test can be factually correct and still have negative value. Accurately describing current behavior is not sufficient; the protected behavior must be important enough to justify the future friction. ## Expected effects of different changes