docs: codify agent-workflow discipline learned in production

AGENTS.md

@@ -70,6 +70,13 @@ User feedback on the running app is handled by an orchestrating agent that deleg
 - **Accept.** An independent acceptance subagent (model route `zai-coding-cn/GLM-5.3-Flash`; never the instance that wrote the code) reviews the diff against the ticket's acceptance criteria, runs the targeted gates (`pnpm typecheck`, `pnpm build`, and the test suites touching the change), and for UI-visible changes verifies the behavior in a browser with screenshots against the dev server (`pnpm webui:dev`, frontend at `http://127.0.0.1:18091/`). The full `pnpm verify` profile is left to CI.
 - **Ship.** Open a pull request that references the ticket and attaches the acceptance report (diff verdict, gates run, evidence screenshots). Enable auto-merge (squash); the PR merges once CI is green, and the branch is deleted. Direct pushes to the default branch remain forbidden.
 
+Discipline learned the hard way — apply in every round:
+
+- **Self-check before acceptance.** The development subagent live-verifies every render path in its own isolated instance before acceptance sees the change; acceptance is never the first pair of eyes on a render path. Pin render-critical wiring with a regression test — a static-source tripwire is acceptable only when the suite has no render harness — and drive internal code paths in tests, not just exported names (an export-alias reference bug once shipped dead code that its own unit tests passed).
+- **Process safety.** Never signal processes by name or pattern (`pkill`, `killall`, process-group kills) — they hit unrelated instances, including other agents' test servers and the live dev instance. Signal only PIDs you personally spawned, verified with `ps` first. Isolated test instances run on their own ports with their own `MCODE_WEBUI_DATA_DIR`.
+- **Test hygiene.** Tests that spawn `server.js` must set `MCODE_WEBUI_{SETTINGS_PATH,EVENTS_PATH,SESSIONS_DB,UPLOAD_DIR}` to per-test temporary paths — enforced by `scripts/test-isolation-lint.check.mjs` in the `test:release-tools` gate. Close every server/socket in teardown; one leaked handle hangs an entire gate (this failed CI twice).
+- **Model routes.** Verify route availability in the session's model catalog before dispatching. Development: `minimax-cn/MiniMax-M3`, with `zai-pro/GLM-5.3` preferred for backend work and `zai-pro/GLM-5.3-Flash` for frontend work when those routes are allowed. Acceptance: the configured reviewer route (e.g. `mimo-pro/mimo-v2.6-pro`), falling back to `zai-coding-cn/GLM-5.3-Flash` — always an instance that did not write the code. A route that fails mid-task is swapped immediately and the work handed over with explicit context; the orchestrator recovers wedged dev-server processes by verified PID only.
+
 ## Boundaries
 
 Do not reference internal hosts, generated IDL, or private services; `check:source` catches known patterns but does not replace publication review. Do not restore paths listed in `scripts/lib/retired-sources.mjs` or remove supported capabilities to make standalone checks pass. Do not commit account data, sessions, logs, credentials, or real user content; use temporary data directories and synthetic test inputs. Documentation and commit messages are written in English; preserve the required languages of localized product strings and bundled runtime prompts. See `CONTRIBUTING.md`.