# AGENTS.md Update Guidelines

## Evidence Contract

Every proposed line must be:

- specific to the repository or explicitly requested global scope;
- supported by a file, manifest, safe command result, or user-confirmed fact;
- durable enough to help future sessions;
- placed at the narrowest scope where it is true;
- expressed in the shortest actionable form that preserves meaning.

Never add secrets, credential values, personal data, unverified claims,
session narrative, generic advice, facts obvious from names, or one-off fixes.

## Safe Verification

Prefer read-only inspection. Run a command only when it is relevant, safe, and
unlikely to change external state. Do not deploy, publish, migrate data, write
credentials, or invoke destructive cleanup merely to validate guidance.

If a command cannot safely be run, label it unverified rather than treating it
as current.

## Precedence and Size

- Select `AGENTS.override.md` before `AGENTS.md` at each directory.
- Build the active project chain from root to current working directory.
- Later, closer guidance wins on conflict.
- Parent guidance remains active unless a later instruction contradicts it.
- Flag duplicate or conflicting rules across selected files.
- Compare combined selected-file bytes with configured
  `project_doc_max_bytes`, using 32 KiB when no override is evidenced.

## Diff Contract

For every proposed change:

```markdown
### Update: path/to/AGENTS.md

**Why:** `package.json` defines `test:unit`, while the documented `npm test`
command does not exist.

```diff
- Run `npm test` before handoff.
+ Run `npm run test:unit` before handoff.
```
```

Group diffs by destination. After all diffs, ask which changes the user wants
applied. Do not edit before that approval.

## Post-Edit Validation

- Re-read every changed file.
- Rebuild the active chain for the affected subtree.
- Check for conflicts and duplication.
- Verify changed commands and paths.
- Recalculate the combined byte count.
- Report exactly what was changed and what could not be verified.