docs: strengthen AGENTS.md to reduce recurring agent error patterns (GH#948)

AGENTS.md

@@ -186,6 +186,24 @@ wp db reset --yes && cd ../wordpress && ./reset.sh  # full DB + WordPress reset
 
 Recurring error patterns observed in this codebase. Review before starting any session.
 
+### Quick Session Checklist (top 4 recurring failures)
+
+**Before writing a single line of code, verify these four things:**
+
+1. **No webfetch** — never construct or guess a URL. WordPress docs, Stripe/PayPal API docs,
+   GitHub URLs, PHP manual, npm package docs: all fail. Read the codebase instead (see
+   [No External URL Fetching](#no-external-url-fetching)).
+2. **Verify paths exist before reading** — run `git ls-files '<path>'` first. An empty result
+   means the file does not exist; do not attempt to read it (see table below).
+3. **Read immediately before every edit** — the Edit tool requires a Read call earlier in the
+   same conversation turn on that exact file. `Read(A) → Edit(A)` is correct. `Read(A) →
+   Read(B) → Edit(A)` fails if A's content changed, and will always fail on session restart.
+   Never read multiple files upfront and edit them later.
+4. **Check tool prerequisites** — before any lint, test, or analysis command, confirm:
+   - `ls vendor/autoload.php 2>/dev/null || echo "run: composer install"`
+   - `ls node_modules/.bin/eslint 2>/dev/null || echo "run: npm install"`
+   - `ls /tmp/wordpress-tests-lib/includes/bootstrap.php 2>/dev/null || echo "run: bin/install-wp-tests.sh"`
+
 ### File Discovery — `.dist` Config Convention
 
 Config files are committed as `.dist` versions; un-suffixed copies are gitignored and may not exist locally:
@@ -229,6 +247,10 @@ read them will produce `read:file_not_found`:
 | `lib/` | Does not exist; use `inc/` for PHP code, `assets/` for frontend |
 | `languages/` | Does not exist; i18n files are in `lang/` |
 | `.env`, `.env.example` | Does not exist; no local env config stored in this repo |
+| `inc/functions.php` | Does not exist as a single file; functions live in `inc/functions/*.php` |
+| `inc/admin.php` | Does not exist; admin pages live in `inc/admin-pages/` and `inc/admin/` |
+| `SECURITY.md` | Does not exist in this repo |
+| `coverage-html/**`, `coverage.xml` | Generated by test:coverage run, gitignored, may be absent |
 
 Always verify a file is tracked before reading it with `git ls-files '<path>'`. An empty result means the file does not exist in the repo.
 
@@ -240,8 +262,8 @@ guessing a docs URL from a package name) account for the majority of `webfetch:o
 in this codebase.
 
 Do **not** use webfetch for WordPress documentation, PHP manual pages, Stripe/PayPal API docs,
-BerlinDB documentation, npm package docs, or any other developer documentation URLs — these
-requests consistently fail.
+BerlinDB documentation, WooCommerce docs, npm package docs, WP Plugin Handbook, or any other
+developer documentation URLs — these requests consistently fail.
 
 Do **not** use webfetch for GitHub URLs (issues, PRs, raw content, commits). Use the `gh` CLI
 instead:
@@ -276,6 +298,23 @@ Do **not** read all files at session start and edit them later. The pattern `Rea
 
 When working on multiple files in the same session: read each file immediately before editing it, not at the start of the session. Reading file A, then file B, then editing file A will fail if A's content changed between your read and your edit.
 
+**Anti-pattern (causes `edit:not_read_first` failure):**
+
+```
+Read(inc/models/class-membership.php)
+Read(inc/managers/class-membership-manager.php)   ← reading a second file resets the "last read" state
+Edit(inc/models/class-membership.php)             ← FAILS: file not read in this turn
+```
+
+**Correct pattern:**
+
+```
+Read(inc/models/class-membership.php)
+Edit(inc/models/class-membership.php)             ← immediate edit after read
+Read(inc/managers/class-membership-manager.php)
+Edit(inc/managers/class-membership-manager.php)   ← immediate edit after read
+```
+
 ### WP-CLI and Bash Prerequisites
 
 `wp` commands require the dev WordPress install at `../wordpress`. Check it exists before running: