From cc51b8470a17b770f8010b3d96edab5a2d3e5f3a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 25 Sep 2026 20:25:36 +0000 Subject: [PATCH] Establish a dedicated agent policy --- AGENTS.md | 6 +-- docs/development.md | 3 ++ docs/policy/agents.md | 90 ++++++++++++++++++++++++++++++++++++ docs/policy/architecture.md | 30 +----------- docs/policy/documentation.md | 2 +- docs/policy/testing.md | 2 +- 6 files changed, 98 insertions(+), 35 deletions(-) create mode 100644 docs/policy/agents.md diff --git a/AGENTS.md b/AGENTS.md index 355653ed..b9989e27 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,5 @@ Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide. -For every planning and implementation task, follow the -[`Implementation Discipline`](docs/policy/architecture.md#implementation-discipline): -keep machinery proportionate, do not invent restrictions, and do not elevate -incidental implementation details into repository policy. +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 09905c2d..08ef5862 100644 --- a/docs/development.md +++ b/docs/development.md @@ -9,6 +9,9 @@ the [README](../README.md) for product context, [Architecture](policy/architectu for system boundaries, and [Internal Overview](internal/overview.md) for the implemented component map. +Read [Agent Policy](policy/agents.md) before recommending, planning, or +implementing changes. It owns implementation discipline and local commit rules. + ## What To Read | When working on | Read | Why | diff --git a/docs/policy/agents.md b/docs/policy/agents.md new file mode 100644 index 00000000..baa25cfd --- /dev/null +++ b/docs/policy/agents.md @@ -0,0 +1,90 @@ +# Agent Policy + +**Base Policy Version:** 1.1 + +**Last Updated**: 2026-09-25 + +**Upstream Source:** `policy` commit `45591a79004c6811950f14dca554f6ff69b7f58e`. + +Notarius adaptations preserve operator choice, existing explicit contracts, and +the deployment-permissions example below. + +## Purpose + +Agents working in this repository must read and adhere to the following house rules. + +## Implementation Discipline + +Simplify the mechanism, not the user's choices. + +**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. Existing +explicit contracts remain authoritative; changing or weakening one requires a +deliberate decision rather than being inferred from these principles. + +[ADR-0017](../adr/0017-defer-cache-access-policy-to-deployment.md) illustrates +why Unix deployments own cache access policy through permissions, umask, setgid, +and default ACLs. Notarius retains its separately adopted correctness boundaries. + +## 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/architecture.md b/docs/policy/architecture.md index 832025d0..14adcdef 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -38,35 +38,7 @@ Notarius is contract-first without being abstraction-heavy. Interfaces and extension points should protect demonstrated boundaries. New abstraction is not itself an architectural goal. -## 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. - -**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. - -[ADR-0017](../adr/0017-defer-cache-access-policy-to-deployment.md) illustrates -these principles. Notarius previously elevated private cache creation modes -into application policy even though Unix deployments already express access -policy through directory permissions, process umask, setgid inheritance, and -default ACLs. The revised design retains application-owned correctness -boundaries while leaving deployment security policy to the operator. +Implementation discipline is owned by [Agent Policy](agents.md). ## Layers And Dependency Direction diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 2b196ea1..30df0b8a 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -38,7 +38,7 @@ policy, default, or limit as authoritative merely because the current code implements it. Documentation may accurately describe current behavior without making it a permanent requirement; distinguish descriptive behavior from normative policy. The -[implementation-discipline rules](architecture.md#implementation-discipline) +[implementation-discipline rules](agents.md#implementation-discipline) own the criteria for adopting product restrictions and for elevating behavior into repository policy. diff --git a/docs/policy/testing.md b/docs/policy/testing.md index 10097bbe..17e5cf48 100644 --- a/docs/policy/testing.md +++ b/docs/policy/testing.md @@ -91,7 +91,7 @@ Tests must not create a stronger product contract than the requirement they protect. In particular, do not turn an incidental limit, restriction, permission choice, validation rule, or implementation default into policy by asserting it without an expressly selected contract. Follow the -[implementation-discipline rules](architecture.md#implementation-discipline) +[implementation-discipline rules](agents.md#implementation-discipline) when deciding what behavior deserves durable protection. Before adding or retaining a test, ask: