Align policies with the standard and record their provenance

docs/policy/agents.md

@@ -1,19 +1,20 @@
 # Agent Policy
 
-**Base Policy Version:** 1.1
+**Base Policy Version:** 1.3
 
-**Last Updated:** 2026-09-23
+**Last Updated**: 2026-09-27
+
+**Upstream Source:** [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md)
 
 ## Purpose
 
-Agents must follow these house rules before recommending, planning, or
-implementing repository changes.
+Agents must read and follow these rules.
 
 ## Implementation Discipline
 
-Write the simplest idiomatic code that satisfies the user's request.
-Simplify the mechanism, not the user's choices. Do not implicitly strengthen
-requirements, restrictions, or guarantees.
+**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
@@ -28,41 +29,48 @@ 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.
+
+## Promptkit Contract Authority
+
+The following clarification preserves Promptkit's established distinction
+between implementation choices and authorized contracts.
+
 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.
-
-**Do not invent guarantees.** Do not strengthen public contracts, guarantees,
-or invariants beyond those expressly requested by the user.
-
-**Use the standard library.** Prefer simple, idiomatic standard-library
-implementations when they satisfy the requested behavior. Do not add custom
-power-loss protection or defenses against privileged concurrent filesystem
-actors unless expressly required. Preserve existing repository contracts.
+Existing explicit contracts remain authoritative; changing or weakening one
+requires a deliberate decision. 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
+By default, commit each completed, nonempty 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.
+documentation.
 Complete the appropriate validation before committing. If work is incomplete or
-validation is blocked, report that state rather than presenting it as completed.
+validation is blocked, report that state accurately.
 
 Before committing:
 
@@ -70,10 +78,10 @@ Before committing:
    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.
+   only when every included change belongs to that unit. Preserve unrelated
+   staged and unstaged work.
+4. Review `git diff --staged` and run appropriate checks for the change. Reuse
+   successful checks for unchanged content.
 5. Review `git log --oneline -n 10` and use
    `git commit -m "<concise plain-English commit message>"`.
 6. Report the commit identifier and any remaining uncommitted work.