audita/docs/policy/agents.md

Agent Policy

Base Policy Version: 1.3

Last Updated: 2026-09-28 Upstream Source: Standard Repository Policies agents

Purpose

Agents must read and follow these 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.

Codebase Discovery

This project uses codebase-memory-mcp to maintain a knowledge graph of the codebase. Always prefer its graph tools over grep, glob, or file search for code discovery. If the project is not indexed, run index_repository first.

Use this order:

1. search_graph to find functions, classes, routes, and variables by pattern.
2. trace_path to trace callers and callees.
3. get_code_snippet to read a specific function or class.
4. query_graph for complex graph queries.
5. get_architecture for the high-level project summary.

Fall back to grep or glob for string literals, error messages, configuration values, non-code files, or when the graph tools return insufficient results.

Examples:

• Find a handler: search_graph(name_pattern=".*OrderHandler.*").
• Find callers: trace_path(function_name="OrderHandler", direction="inbound").
• Read source: get_code_snippet(qualified_name="pkg/orders.OrderHandler").

Git Commit Policy

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. Complete the appropriate validation before committing. If work is incomplete or validation is blocked, report that state accurately.

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. 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.

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.