diff --git a/AGENTS.md b/AGENTS.md index 5d094ee3..d1b785bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,25 +5,23 @@ repository. Keep it project-specific and safe to publish. Do not put personal machine setup, private network details, credentials, tokens, or local-only workflow notes here. -## Read first +## Documentation by task -Before making changes, read: - -1. `README.md` -2. `CONTRIBUTING.md` -3. `docs/CONTRACTS.md` -4. `CHANGELOG.md` - -For architecture, testing, or setup work, also read the matching reference: +Use the references that match the change; there is no blanket reading list for +unrelated work. Keep subsystem-specific safety and contract requirements below. +- `README.md` for product behavior, setup, usage, and the docs index +- `CONTRIBUTING.md` for contribution scope, PR format, and review requirements +- `docs/CONTRACTS.md` to find the contract/RFC for the subsystem being changed +- `docs/GUIDELINES.md` for bug-class coverage, state ownership, and evidence standards +- `CHANGELOG.md` for release-history questions; ordinary PRs do not edit it - `ARCHITECTURE.md` for design constraints and current module layout -- `TESTING.md` for local verification commands and manual test guidance +- `TESTING.md` for local verification commands and relevant manual checks - `docs/onboarding.md` for first-run onboarding behavior - `docs/troubleshooting.md` for diagnostic flows - `docs/rfcs/README.md` for larger RFCs and state/durability contracts - -For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before -changing layout, interaction flow, themes, chat rendering, or composer chrome. +- `docs/UIUX-GUIDE.md` and `DESIGN.md` for layout, interaction flow, themes, + chat rendering, and composer chrome ## Onboarding and reinstall support @@ -73,39 +71,34 @@ Follow that checklist's safety rules: in both the `rsync` and `cp -a` paths — `/opt/hermes` may contain subdirectories with restricted permissions (e.g. `.playwright/`). -## Before you open a PR — the change guidelines +## Completion and verification -Read [`docs/GUIDELINES.md`](docs/GUIDELINES.md) in full before non-trivial work. It is the -distilled set of habits that get a change merged in one review round instead of several. The -compressed form: +A change is ready for review when: -1. **Fix the class, not the instance.** A bug usually has siblings — other call sites, backends, - companion endpoints, layouts, exit paths. Find them all and fix the shared chokepoint, or name - the ones you left out of scope. -2. **Trace one authoritative value end-to-end** (`input → normalize → decision → action → persist → - cleanup`); the code that *decides* and the code that *acts* must use the same resolved value. -3. **When you can't confirm something, fail closed and say so.** Never take the permissive branch on - uncertainty; never report a failure as success. "Unknown" is not "allowed." -4. **Enumerate the state-space before editing** — entry point, backend, item count (0/1/many), every - lifecycle exit (success/error/cancel/replace/teardown), auth on/off, concurrency, hostile input — - and cover each or mark it out of scope. Most redo rounds are one un-considered dimension. -5. **Assume inputs and check-then-use gaps are adversarial** — validate at the point of use (hold a - handle, don't re-resolve a path), scope caches by complete identity, handle crafted input. -6. **A test must fail before your fix and pass after it.** Assert observable behavior, not a source - string or a mock of the thing under test; use multiple items if selection is what's being tested. -7. **Name the owner of every piece of state and prove it's released on every exit** (success, error, - cancel, replace, shrink, teardown) — not just the happy path. -8. **Fallbacks/defaults are contracts — extend the mechanism, don't copy it.** Editing N parallel - blocks identically means you missed a chokepoint (e.g. new copy goes in the `en` locale only). -9. **The diff is the task and nothing else.** Extras go in the PR description, not the diff; run the - affected + neighboring tests before opening. -10. **A visible control costs attention on every visit** — place it by frequency of use and by where - mainstream chat apps put the equivalent, not by where your diff already is; verify with - before/after images at desktop and narrow widths. +- The requested scope is implemented, with related call sites and lifecycle + paths covered or explicitly identified as out of scope; unrelated cleanup is absent. +- Behavior changes have observable regression evidence where practical, including + proof that a bug-fix test fails before the fix and passes after it. Evidence covers + affected and neighboring tests, not only new tests. +- State changes identify the authoritative value and its owner, use that value + through decision, action, and persistence, and account for cleanup on every exit. + Fallbacks and defaults extend the existing mechanism rather than duplicate it. +- UI changes include before/after evidence at desktop and narrow widths and + cover relevant mobile interactions; controls fit their frequency of use. +- Relevant docs are current. The PR body follows `CONTRIBUTING.md`, includes + `Contract Routing` (and `Contract Change` for intentional contract changes) + where required by `docs/CONTRACTS.md`, and reports actual commands, outcomes, + assumptions, and anything not verified. Mocks are not proof of external behavior. -Show the work in the PR body: the siblings you found, proof the test failed before the fix, the -verification run, before/after images for visible changes, and an explicit list of what you could -not verify. +Within the requested scope, you may run local tests with disposable fixtures, +fix failures caused by the change, and rerun affected tests without asking for +approval at each step. Use `./scripts/test.sh` for pytest as specified above. +This permission applies only with confirmed isolated state and no live +credentials or services; the runner manages Python dependencies but is not a +network sandbox. It does not authorize modifying real state, handling credentials, +restarting existing services, or exposing the app beyond localhost. Those actions +require explicit human approval and the onboarding safety rules still apply. +If verification is blocked, report the blocker rather than claim completion. ## Local state and secrets @@ -113,6 +106,11 @@ Hermes WebUI can read and write real agent state, sessions, workspaces, credentials, and cron data. Treat local validation as potentially destructive unless you have confirmed the active state directories. +For authority, capability, identity, or containment checks, fail closed when +safety cannot be confirmed: unknown is not allowed. Validate adversarial inputs +at the point of use, account for check-then-use races, and scope caches by the +complete identity so profiles and sessions cannot leak into each other. + Prefer isolated trial state for experiments: ```bash