From c25e1feef33fbfe74a9368ec190d2e3e02a97317 Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 11:41:23 +0200 Subject: [PATCH 1/9] docs: streamline agent instructions Signed-off-by: Gjermund Garaba --- cli/AGENTS.md | 21 +-- cli/cmd/ibc/AGENTS.md | 19 +-- cli/internal/config/AGENTS.md | 15 -- cli/internal/server/AGENTS.md | 18 +-- cli/internal/store/AGENTS.md | 53 +------ docs/6-ibc-cli/5-configuration.md | 4 +- docs/6-ibc-cli/6-cli-commands.md | 4 +- docs/6-ibc-cli/7-api.md | 4 +- docs/6-ibc-cli/tools/AGENTS.md | 230 +++++------------------------- docs/6-ibc-cli/tools/refgen.py | 10 +- e2e/AGENTS.md | 36 ++--- e2e/internal/harness/AGENTS.md | 11 +- proto/AGENTS.md | 12 +- 13 files changed, 89 insertions(+), 348 deletions(-) delete mode 100644 cli/internal/config/AGENTS.md diff --git a/cli/AGENTS.md b/cli/AGENTS.md index e7b7bdbef..3ff5f0477 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -1,27 +1,18 @@ -# IBC CLI Development Guide for AI Agents +# IBC CLI -- Use `make lint-fix` to auto-format and lint code before finishing work. -- Don't add verbose comments. Be concise. +- Run the relevant tests and `make lint` from this directory before finishing. - `gen/` at the repository root holds generated code only, and its layout is fixed by an ADR — don't move it or put anything handwritten there. Generator scripts belong in the root `scripts/` directory, not beside their output. The one exception is `gen/README.md`, which documents the tree. -- Repository-wide black-box e2e lives in `../e2e`, with its harness in - `../e2e/internal/harness` as a separate Go module. The real relayer submits packets through - ICS26Router with attestation proofs signed by harness-managed attestors. Keep - `make -C e2e test` green when changing that transport contract. +- From the repository root, keep `make -C e2e test` green when changing the CLI transport contract + exercised by the repository-wide black-box tests. ## Documentation generated from this code -The reference pages under `docs/6-ibc-cli/` carry tables generated from this -directory. **If you change anything here, the documentation must be regenerated -before the pull request is opened**, and the regenerated pages belong in the -same pull request as the code. - -Follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). -It covers what to run, what the generator refuses and why, and what you may -write yourself. +When changing commands or flags, configuration, cited behavior, or build inputs represented in the +CLI reference pages, follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). Never hand-edit between a `` marker and its `END`: the next run overwrites it. diff --git a/cli/cmd/ibc/AGENTS.md b/cli/cmd/ibc/AGENTS.md index 2589452dc..42905128b 100644 --- a/cli/cmd/ibc/AGENTS.md +++ b/cli/cmd/ibc/AGENTS.md @@ -1,15 +1,10 @@ -# CLI development (located in cmd/ibc/) +# CLI commands -1. Use a single `init()` function in main.go to wire all subcommands. Never create init() per CLI file. -2. Commands implemented in this package should be variables and start with a `cmd*` prefix. The relayer - family is constructed by an importable command package because its transport types are shared with - the e2e harness. Examples for commands that remain here: - - `ibc attestor run` corresponds to `var cmdAttestorRun = ...`; - - `ibc config validate` corresponds to `var cmdConfigValidate = ...`; - - `ibc migrate up` corresponds to `var cmdMigrateUp = ...`; -3. Command implementations in this package should use `func commandName(cmd *cobra.Command, args []string) error`. - Importable command packages may pass command-owned option structs to injected handlers so flags stay - local to the command constructor. Be consistent within each command family. -4. Global CLI flags such as `--home` or `--config` belong in `config.FlagSet`. Add new global flags there, and don't use a separate variable if it can be global. +- Use the single `init()` in `main.go` to wire subcommands; do not add per-file `init()` functions. +- Define commands implemented in this package as variables with a `cmd*` prefix. Importable command + packages may construct command families whose transport types are shared outside this package. +- Package-local handlers use `func commandName(cmd *cobra.Command, args []string) error`. Importable + command packages may pass command-owned option structs to injected handlers. +- Put global flags such as `--home` and `--config` in `config.FlagSet`. diff --git a/cli/internal/config/AGENTS.md b/cli/internal/config/AGENTS.md deleted file mode 100644 index e4ca34acf..000000000 --- a/cli/internal/config/AGENTS.md +++ /dev/null @@ -1,15 +0,0 @@ - - -# Config package development rules - -1. Follow the following code blocks ordering (excluding test cases): - - exported interfaces - - unexported interfaces - - exported consts - - unexported consts - - exported types definitions. Nested types should have child definitions below parent - - `Default*()` `Declare*() functions - - exported methods, same order as as types - - unexported methods - - exported functions - - unexported functions \ No newline at end of file diff --git a/cli/internal/server/AGENTS.md b/cli/internal/server/AGENTS.md index 0aec9598d..a23297160 100644 --- a/cli/internal/server/AGENTS.md +++ b/cli/internal/server/AGENTS.md @@ -1,15 +1,9 @@ -# ConnectRPC Guide for AI Agents +# ConnectRPC adapters -Development flow: -1. Update raw protos in `proto/cli/*`. -2. Run `make codegen` (proto and mocks included). -3. Implement ConnectRPC handlers in `attestor_handler.go` or `relayer_handler.go`. -4. Add missing `AttestorService`/`RelayerService` methods if needed. - - Use idiomatic Go: `ctx` first. - - If a service method needs more than 3 args, use a DTO struct. -5. Keep `server/` as an adapter only: - - Convert ConnectRPC/proto types to service DTOs. - - Call the service interface. - - Map domain errors to `connect.Code*`. \ No newline at end of file +Keep this package as a transport adapter: convert ConnectRPC/proto types to service DTOs, call the +service interface, and map domain errors to `connect.Code*`. + +When an RPC schema changes, update `proto/cli/` and run `make codegen` from `cli/` before updating +the handler. diff --git a/cli/internal/store/AGENTS.md b/cli/internal/store/AGENTS.md index 3b21ab516..df84c0d5d 100644 --- a/cli/internal/store/AGENTS.md +++ b/cli/internal/store/AGENTS.md @@ -1,54 +1,15 @@ -# Store guidelines for AI Agents +# Store `store.Store` is the single entrypoint for other packages that rely on DB. -## I. Creating migrations - -To create a migration, run the script from the project's root (./cli) - -```bash -go run scripts/migratenew.go add-packet-index -✔︎ Created /path/to/ibc/cli/internal/store/migrations/sqlite/002-add-packet-index.sql -✔︎ Created /path/to/ibc/cli/internal/store/migrations/postgres/002-add-packet-index.sql -``` - -The script prints absolute paths and assigns the next migration number automatically. - -Edit both `migrations/sqlite/*.sql` and `migrations/postgres/*.sql`; keep behavior identical, syntax dialect-specific. - -## II. Query creation, code generation - -For types & queries generation, `sqlc` tool is used. - -When creating `sqlc` SQL queries in `queries/*`, use "macros" to build unified files that -can be used both for sqlite and postgres. Example: - -```sql --- name: GetAuthorByName :one -SELECT * -FROM authors -WHERE lower(name) = sqlc.arg(name); --- "sqlc.arg" is a macro, "sqlc.narg" is similar, but makes a param nullable --- macros docs: https://docs.sqlc.dev/en/latest/reference/macros.html - --- >>> EXPANDS TO >>> - --- name: GetAuthorByName :one -SELECT * -FROM authors -WHERE lower(name) = ?; -``` - -- (re)generate bindings with `make codegen-sql`. +- From `cli/`, create paired migrations with `go run scripts/migratenew.go `. Edit both + `migrations/sqlite/` and `migrations/postgres/`; keep their behavior equivalent while using each + dialect's syntax. +- Write shared queries in `queries/` with sqlc arguments such as `sqlc.arg` and `sqlc.narg`, then run + `make codegen-sql` from `cli/`. - Don't edit generated files in `repository/sqlite` or `repository/postgres`. - -### III. Unified repository layer - -After ensuring that the new migration is in place and the sqlc models and queries have been generated: - -- Add public persistence methods to `Repository` interface in `store.go`. Use idiomatic Go +- Add public persistence methods to the `Repository` interface in `store.go`. - Implement every method in both `store_sqlite.go` and `store_postgres.go`. - Return domain structs from `store.go`, not generated sqlc row types. -- Implement basic input validation. if method arg is a struct, implement `.Validate() error` for it diff --git a/docs/6-ibc-cli/5-configuration.md b/docs/6-ibc-cli/5-configuration.md index 6d94d7a4a..de7679797 100644 --- a/docs/6-ibc-cli/5-configuration.md +++ b/docs/6-ibc-cli/5-configuration.md @@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request. +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md. --> diff --git a/docs/6-ibc-cli/6-cli-commands.md b/docs/6-ibc-cli/6-cli-commands.md index 2b0edcd31..447459ab7 100644 --- a/docs/6-ibc-cli/6-cli-commands.md +++ b/docs/6-ibc-cli/6-cli-commands.md @@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request. +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md. --> diff --git a/docs/6-ibc-cli/7-api.md b/docs/6-ibc-cli/7-api.md index 9f3ee7f51..eac6725eb 100644 --- a/docs/6-ibc-cli/7-api.md +++ b/docs/6-ibc-cli/7-api.md @@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request. +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md. --> diff --git a/docs/6-ibc-cli/tools/AGENTS.md b/docs/6-ibc-cli/tools/AGENTS.md index 29e470c2f..738172aab 100644 --- a/docs/6-ibc-cli/tools/AGENTS.md +++ b/docs/6-ibc-cli/tools/AGENTS.md @@ -2,223 +2,69 @@ # Updating the reference pages -You are here because something under `cli/`, `proto/` or `gen/` changed. That -includes changes that rename no symbol at all: the `go` directive in a `go.mod` -is quoted as a prerequisite on two of these pages, and a dependency bump that -moves it is a documentation change. Do not skip this for a merge that only -touches build files. - -Three pages carry tables derived from that surface: - -| Page | Covers | Derived from | -|------|--------|--------------| -| [5-configuration.md](../5-configuration.md) | every key in `ibc.yml`, and the example config | the config structs in `cli/internal/config/`, and the yaml fixture that package's tests load | -| [6-cli-commands.md](../6-cli-commands.md) | every command and flag | the built binary's command tree, plus the wiring in `cli/cmd/ibc/` | -| [7-api.md](../7-api.md) | all three gRPC services (relayer, attestation, prover) | `proto/cli/*.proto` | - -Do this **before the pull request is opened**, in the same pull request as the -code. Run everything from the repository root. Three things must be on PATH: - -- `python3` — the generator uses only the standard library -- a **Go toolchain** — both the CLI and config pages build the binary and ask - it: a flag's default is only honest once assembled, and whether a config key - is required is asked by removing it and seeing whether the binary objects -- **`buf`** — the API page is generated from the descriptor set it compiles, - which is how this repository already builds its protos (`proto/buf.gen.yaml`). - Install it from https://buf.build/docs/installation - -None of the three is optional and none has a fallback. Without `buf` the API -page refuses rather than falling back to reading the `.proto` as text: a reader -that understands the schema less well than the compiler is how a page goes -quietly wrong when the schema grows a construct. - -[REFERENCE.md](REFERENCE.md) is the catalogue: every plan kind, the constants -you may edit, the probe fixtures behind the required column, and the two -formats below. This file is the procedure. - -[AUDIT.md](AUDIT.md) is separate work: checking whether the pages are *true* -rather than current. `--check` cannot answer that, so nothing below calls for -it — read it when that is the question you have. - -**The one rule: never edit between a `` and its `END`.** -Those blocks are rewritten from source, so an edit there disappears the next -time anyone regenerates — a change that looks like a fix and is not. Everything -else on those pages is yours: prose, headings, section order, examples. - -The example config is generated like everything else, so `--check` covers it — -but it is *copied* from the fixture the Go tests validate, so the way to change -it is to edit `cli/internal/config/testdata/sample.yml`, not the page. - -What the generator does not watch is the other pages in `docs/6-ibc-cli/` — the -overview, the tutorial, the two guides — which describe this same surface in -hand-written prose. **They carry no markers and no citations, so nothing in this -file will ever name them.** Step 7 is how you check those, and it is the only -thing that does. - -## 1. Find out what moved +Use this procedure when a change affects the CLI commands or flags, configuration surface, public +API under `proto/cli/`, code cited by the reference prose, or build inputs represented on the pages. +Internal changes that cannot affect those surfaces do not require regeneration. -```sh -python3 docs/6-ibc-cli/tools/refgen.py all --check # a diff per stale table -python3 docs/6-ibc-cli/tools/refgen.py all --plan # the work order, as JSON -``` - -Neither writes to a page. Both build the CLI and run every one of its commands -to read what they require, so they are not free and not inert. +The generated pages are: -`--plan` is the list to work from; **REFERENCE.md explains every kind it can -report, and the exit codes.** `--list-regions` prints the stale region ids -alone: the prose to re-read in step 4. +| Page | Derived from | +|------|--------------| +| [5-configuration.md](../5-configuration.md) | config structs and `cli/internal/config/testdata/sample.yml` | +| [6-cli-commands.md](../6-cli-commands.md) | the built command tree | +| [7-api.md](../7-api.md) | `proto/cli/*.proto` | -One kind is worth knowing before you see it. If you renamed or moved a Go -symbol, expect `stale_citation`: sentences in the prose cite the code they came -from, by path and symbol, and the check refuses when one no longer resolves. It -is not asking you to repoint the comment — it is asking whether your change made -that *sentence* wrong. REFERENCE.md has the format. +Run the commands below from the repository root. They require Python, Go, and `buf`. -## 2. Resolve everything that needs a decision +Never edit between a `` marker and its `END`. To change the generated example +configuration, edit `cli/internal/config/testdata/sample.yml`. -Nothing is written while any of these remain, and each is named. **Read -REFERENCE.md before resolving anything** — it says what each kind means and -what fixes it. +## 1. Find what moved -Three things govern every one of them: +```sh +python3 docs/6-ibc-cli/tools/refgen.py all --check +python3 docs/6-ibc-cli/tools/refgen.py all --plan +``` -- **Fix it at the source where you can.** A doc comment on the declaration - beats an entry in this directory, because the page then documents itself. -- **If the code does not say what something means, ask the person you are - working with.** A guess reads exactly like knowledge on the page. -- **Hand it back where the decision is not yours.** See step 6. +Both commands build and run the CLI. The plan names anything that requires a decision. Read +[REFERENCE.md](REFERENCE.md) for the reported plan kinds and exit codes. -**A page blocked by one item still has work you can do.** Resolve everything -else on it — descriptions, markers, sections, prose. Leaving them because the -page will not regenerate yet is how a whole page gets skipped over one line of -protobuf. +## 2. Resolve decisions -**`SKIP_FIELDS` and `CLI_EXCLUDED` delete a row, and nothing checks either for -obsolescence.** A key listed there is gone from the page for good, including -after it is renamed. Never reach for one to make a refusal go away: that -answers a refusal with the short-table-that-reads-complete this tool refuses -everywhere else. Use them only for something readers never write or run. +Fix missing or stale information at its source when possible. Do not guess facts the source does not +establish, use `SKIP_FIELDS` or `CLI_EXCLUDED` merely to silence a refusal, or bypass validation with +`REFGEN_NO_REQUIRED_FLAGS`, `REFGEN_NO_REQUIRED_KEYS`, or `REFGEN_NO_BUILD`. Report an unresolved +decision as a blocker using the hand-back format in [REFERENCE.md](REFERENCE.md). -## 3. Heal the tables +## 3. Regenerate ```sh python3 docs/6-ibc-cli/tools/refgen.py all ``` -Deterministic. Run it as often as you like. - -## 4. Correct the prose the code has overtaken +## 4. Update prose -Regenerating repairs a table and leaves the paragraph above it saying the old -thing. For every region that moved, fix the prose beside it — a key that gained -a default the text still calls required, an example that no longer works, a -sentence about a flag that is gone. **The code is the authority.** Match the -page you are writing into; do not restate a table in words. +Read each changed region against its source and correct the surrounding prose. Also update the +hand-written pages in `docs/6-ibc-cli/` when the change affects behavior, examples, defaults, output, +or configuration that they describe; the generator cannot detect those inconsistencies. -## 5. Check your work +## 5. Verify ```sh -python3 docs/6-ibc-cli/tools/refgen.py all --check # must be clean +python3 docs/6-ibc-cli/tools/refgen.py all --check ``` -Then read each region you touched against the code it came from, once. Running -twice and changing nothing proves the tool is stable, not that it is right. - -That is the whole check **unless this pull request changes `refgen.py`** — the suites below -test the generator, not the documentation. Budget about a minute for the unit -suite and **ten or more for the end-to-end one** — it builds the binary -repeatedly. If your tool has a timeout, run it in the background rather than -reading the overrun as a hang. +If `refgen.py` changed, also run: ```sh -# only if you changed refgen.py python3 docs/6-ibc-cli/tools/test-refgen.py python3 docs/6-ibc-cli/tools/test-refgen-e2e.py ``` -**The suites read the working tree**, so a refusal you are handing back makes -them fail until it is resolved. That part is expected. **Do not classify those -failures by eye** — a failure can name the refusal you were told to expect and -still be yours. REFERENCE.md gives the comparison that tells them apart. - -## 6. Report what you wrote - -```sh -python3 docs/6-ibc-cli/tools/refgen.py all --report -``` +When preparing a pull request, generate its documentation report with +`python3 docs/6-ibc-cli/tools/refgen.py all --report` and identify any prose written by hand or work +handed back. The documentation work is complete when `--check` is clean or every outstanding item is +reported as blocked. -Put it in the pull request description, and **add one line under *Written by -hand, not derived* for everything you wrote yourself**, naming where it went. -That section is the point of the report: everything above it is as true as the -code, everything below it is only as true as you. - -If something is blocked, **say so; do not go quiet.** Add a *Handed back* -section in the format REFERENCE.md shows, one line per item. Unfinished and -reported is a fine outcome — unfinished and unmentioned is not, because whoever -reads the pull request cannot tell a page you left alone from a page that -needed nothing. - -## 7. Check the pages nothing generates - -The overview, the tutorial and the two standalone guides describe this surface -in prose, in pasteable examples, and in **captured terminal output**. Nothing -checks any of it. - -**Grepping for the names that changed is not enough, and this is the step -people get wrong.** Grep finds a rename. It does not find a behaviour change, -because the sentence that is now false often contains no changed identifier at -all. A real example: `render-config` began merging the deployment into the -whole config instead of printing three sections. Nothing was renamed, every -grep came back clean, and the overview went on describing the old behaviour. - -So work from the change, not from the text. For each thing the diff changes, -ask **what a reader would now see that these pages show**: - -| If the change... | look for | -|---|---| -| alters what a command prints or writes | every sentence describing that command's output, and every captured transcript of it | -| adds or removes a startup step, a migration, a log line | transcripts — a line that should now be *present* cannot be grepped for by its absence | -| changes a count, a total, a version, a duration | the same number quoted anywhere in prose or output | -| changes a default | sentences stating the old value, and examples that relied on it | -| adds a required config key | every pasteable config block, which now fails to load | - -Two shortcuts worth taking, with one trap. A `yaml` block that is a *whole* -config can be checked by running `ibc config validate` against it. Most blocks -on these pages are not: they are fragments a reader pastes *into* a config — a -bare `attestors:` list, a `signers:` entry — and `config validate` rejects each -as an incomplete config, complaining about the fragment rather than the keys. To -check a fragment, splice it into `cli/internal/config/testdata/sample.yml` and -validate that. Any block of captured output can be checked by running the -command that produced it, when it does not need a live chain. - -Say in the report which of these pages you read and what you changed. "I -grepped and found nothing" is not an answer to this step. - -**You are done when** `--check` is clean, or everything outstanding is listed -under *Handed back*. - -## What you must never do - -Write a heading with a placeholder under it. State a value the source does not -state. Edit inside a generated region. Delete a marker the generator still -fills — deleting the pair for something the source no longer has is -`orphaned_marker`, and is correct; the difference is whether the subject is -gone or merely unreadable. - -**Never set `REFGEN_NO_REQUIRED_FLAGS`, `REFGEN_NO_REQUIRED_KEYS` or -`REFGEN_NO_BUILD`.** Two switch off the checks that catch a whole page rendering -every flag or key as optional; the third builds the tables from a stale binary. -The refusals name them for someone who has confirmed the CLI genuinely has no -required flags. You are not that person: if you trip one, it is a hand-back. - -A refusal is not an obstacle to route around. The tool refuses because it would -otherwise publish something it could not verify, and a wrong page is worse than -a missing one: a reader trusts a default, a required flag, a key name, and acts -on it. - -## Not automated yet - -**Nothing runs `--check` for you.** These pages go stale silently, and this -procedure is the only thing that catches it. Run step 1 whenever a change -touches `cli/`, `proto/` or `gen/`. +Read [AUDIT.md](AUDIT.md) only when the task is to establish whether the generated pages are true, +rather than whether they are current. diff --git a/docs/6-ibc-cli/tools/refgen.py b/docs/6-ibc-cli/tools/refgen.py index ccdc6c374..dcc9dc902 100644 --- a/docs/6-ibc-cli/tools/refgen.py +++ b/docs/6-ibc-cli/tools/refgen.py @@ -7,9 +7,9 @@ flag, every config key, and every gRPC message and field. This script builds those tables from the code and writes them onto the pages, replacing only the text inside the GEN markers. Run `refgen.py all` to update them and -`refgen.py all --check` to fail when a page no longer matches the code. Run it -before opening a pull request that changes `cli/`, `proto/` or `gen/`; the -procedure is in AGENTS.md beside this file. +`refgen.py all --check` to fail when a page no longer matches the code. Use it +when changing the commands, configuration, API, or cited code represented by +the pages; the procedure is in AGENTS.md beside this file. A reference page is part prose and part table. The prose is written by a human and the tables are derived from code, so the tables can be regenerated whenever @@ -3237,8 +3237,8 @@ def inherited_by(path): run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request.""" +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md.""" def _notice(): diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index 0c15e2ae5..da57e58fb 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -1,30 +1,14 @@ -# Repository E2E Tests Guide for AI Agents +# E2E tests -This module contains one root repository-level acceptance package: linear Go tests over the -`internal/harness` surface. Tests relay real IBC packets through the real relayer and -Solidity IBC stack (ICS26Router, ICS20Transfer, ICS27GMP) with attestation light clients and -managed attestors. +Read [README.md](README.md) for running tests, environment behavior, matrix commands, and cleanup. -- Run from the repository root: `make -C e2e test` uses fast mode; - `make -C e2e test E2E_MODE=complete|production` selects another mode, and - `E2E_FLAGS='-run TestTransfer_AutoRelay -count=1'` focuses a run. `-e2e.mode` in `E2E_FLAGS` - overrides `E2E_MODE`. `-e2e.load` overrides `E2E_LOAD`; `E2E_LOAD=true` also enables load tests. -- Tests declare portable EVM, controlled-mining, or node-lifecycle requirements. Fast mode may - skip an unresolved requirement; complete and production modes fail it. Fast and complete prefer - Anvil, while production prefers Besu where the requirements allow it. -- Tests start an `Environment` (which realizes Chains, the IBC contract stack, attestation light - clients, and attestors), hold the temporary IBC CLI driver and relayer explicitly, and assert through - route-bound application bindings (ICS20 transfers, ICS27 GMP calls, IFT transfers). This e2e-only setup - lives in `internal/e2etest`; transport-contract tests may call the concrete driver or Relayer directly. -- E2e may import the IBC CLI's public command transport types, generated RPC clients, and signer-keyfile - package for transport and provisioning, but it must not import `cli/internal` or invoke handlers - in process. -- Each test gets a fresh environment. Managed Anvil uses one-second mixed mining; after mining is - paused and resumed it is interval-only, so transaction inclusion may take one second. -- `Environment` cleans up managed resources only. Attached chains remain caller-owned and expose no - harness mining or node-lifecycle controls. -- Run `make -C e2e generate-matrix` after changing requirements or topology, and - `make -C e2e check-matrix` to check the committed matrix. Both require Docker. -- After a hard crash: `make -C e2e clean-dry-run`, then `make -C e2e clean` from the repository root. +- Acceptance tests use `internal/e2etest` environments and assert through route-bound application + bindings. Hold the temporary IBC CLI driver and relayer explicitly. Transport-contract tests may + call the concrete driver or relayer directly. +- Use the IBC CLI's public command transport types, generated RPC clients, and signer-keyfile package for + transport and provisioning. Do not import `cli/internal` or invoke handlers in process. +- Declare test requirements and regenerate and check the matrix after changing requirements or topology. +- Preserve inner quotes in `E2E_FLAGS`, because Make expands it into a shell command: + `make -C e2e test E2E_FLAGS="-run '^(TestA|TestB)' -count=1"`. diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index 3a90cf756..bcb1b5c62 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -1,14 +1,7 @@ -# E2E Harness Development Guide for AI Agents +# E2E harness -This internal package tree of the e2e module is the black-box e2e harness. Its IBC CLI adapter observes the `ibc` binary only through -its public wire surface — CLI commands with JSON output, config YAML, and the status API — and -corroborates outcomes by reading chain state with its own clients. - -- **The wall:** the harness never imports `cli/internal/...` or the stub's guts. It may import - public IBC CLI command transport types, generated RPC clients, and the signer-keyfile package, while - behavior remains observable only through the executable and HTTP surface. - Wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned to instant Anvil. Launch-side readiness uses `chain/evm/poll.Until`; test-application effect and stability observation lives with the e2e-only bindings that interpret those effects. @@ -17,5 +10,3 @@ corroborates outcomes by reading chain state with its own clients. with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt instead of waiting out the kill grace). Don't reintroduce a shell-wrapped entrypoint. StopNode/StartNode fault injection is docker pause/unpause; chain state stays in memory. -- Lint with `make -C e2e lint` from the repository root; the shared root `.golangci.yml` covers the - harness and excludes exported-doc mandates for this internal test surface. diff --git a/proto/AGENTS.md b/proto/AGENTS.md index 551f1420c..eab22bea8 100644 --- a/proto/AGENTS.md +++ b/proto/AGENTS.md @@ -1,15 +1,9 @@ -## Documentation generated from this code +# Generated CLI reference -The reference pages under `docs/6-ibc-cli/` carry tables generated from this -directory. **If you change anything here, the documentation must be regenerated -before the pull request is opened**, and the regenerated pages belong in the -same pull request as the code. - -Follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). -It covers what to run, what the generator refuses and why, and what you may -write yourself. +When changing the public API under `proto/cli/`, follow +[`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). Never hand-edit between a `` marker and its `END`: the next run overwrites it. From 46c61521cf1205e8e26328634637039cbb1da465 Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 12:40:09 +0200 Subject: [PATCH 2/9] docs: clarify agent instruction scope and verification Signed-off-by: Gjermund Garaba --- AGENTS.md | 8 ++++++++ cli/AGENTS.md | 6 ++---- cli/internal/server/AGENTS.md | 4 ++-- cli/internal/store/AGENTS.md | 3 +++ e2e/internal/harness/AGENTS.md | 8 +++++--- proto/AGENTS.md | 5 ++++- 6 files changed, 24 insertions(+), 10 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..984f99320 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,8 @@ + + +# Repository guidance + +- `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, + except `gen/README.md`, which documents the tree. +- Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their + output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 3ff5f0477..2a365f794 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -2,10 +2,8 @@ # IBC CLI -- Run the relevant tests and `make lint` from this directory before finishing. -- `gen/` at the repository root holds generated code only, and its layout is fixed by an ADR — don't - move it or put anything handwritten there. Generator scripts belong in the root `scripts/` - directory, not beside their output. The one exception is `gen/README.md`, which documents the tree. +- Run the relevant tests from this directory. Run `make lint` here when changing Go code or inputs + that affect linting. - From the repository root, keep `make -C e2e test` green when changing the CLI transport contract exercised by the repository-wide black-box tests. diff --git a/cli/internal/server/AGENTS.md b/cli/internal/server/AGENTS.md index a23297160..c3e901661 100644 --- a/cli/internal/server/AGENTS.md +++ b/cli/internal/server/AGENTS.md @@ -5,5 +5,5 @@ Keep this package as a transport adapter: convert ConnectRPC/proto types to service DTOs, call the service interface, and map domain errors to `connect.Code*`. -When an RPC schema changes, update `proto/cli/` and run `make codegen` from `cli/` before updating -the handler. +When an RPC schema changes, update `proto/cli/` and run `make codegen-proto` from `cli/` before +updating the handler. Run `make codegen-mocks` from `cli/` when an affected mocked interface changes. diff --git a/cli/internal/store/AGENTS.md b/cli/internal/store/AGENTS.md index df84c0d5d..3cbf57cc1 100644 --- a/cli/internal/store/AGENTS.md +++ b/cli/internal/store/AGENTS.md @@ -7,6 +7,9 @@ - From `cli/`, create paired migrations with `go run scripts/migratenew.go `. Edit both `migrations/sqlite/` and `migrations/postgres/`; keep their behavior equivalent while using each dialect's syntax. +- For persistence or schema changes, run the relevant tests against both SQLite and PostgreSQL + from `cli/`, with `TEST_POSTGRES=true` and Docker available. PostgreSQL is skipped unless + `TEST_POSTGRES=true`. Report any backend you could not verify. - Write shared queries in `queries/` with sqlc arguments such as `sqlc.arg` and `sqlc.narg`, then run `make codegen-sql` from `cli/`. - Don't edit generated files in `repository/sqlite` or `repository/postgres`. diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index bcb1b5c62..f9d84cec4 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -2,9 +2,11 @@ # E2E harness -- Wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned - to instant Anvil. Launch-side readiness uses `chain/evm/poll.Until`; test-application effect and - stability observation lives with the e2e-only bindings that interpret those effects. +- Chain transaction and application-effect wait budgets derive from the resolved Chain's + `environment.Timing`, never from a literal tuned to instant Anvil. Provider and process startup + and shutdown use separate lifecycle deadlines. Launch-side readiness uses + `chain/evm/poll.Until`; test-application effect and stability observation lives with the e2e-only + bindings that interpret those effects. - **Docker discipline.** Containers/networks carry the `ibc-cli-e2e=true` and `ibc-cli-run=` labels and the `ibc-cli-e2e-` name prefix, with pinned images. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt diff --git a/proto/AGENTS.md b/proto/AGENTS.md index eab22bea8..3a98f7404 100644 --- a/proto/AGENTS.md +++ b/proto/AGENTS.md @@ -1,6 +1,9 @@ -# Generated CLI reference +# CLI API + +When changing schemas under `proto/cli/` or their generation configuration, run +`make -C cli codegen-proto` from the repository root and include the updated bindings in `cli/api/v2/`. When changing the public API under `proto/cli/`, follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). From 2d543b1a8a8108740f0466da3be44b0241efcdab Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 13:39:05 +0200 Subject: [PATCH 3/9] docs: align agent guidance with repository behavior Signed-off-by: Gjermund Garaba --- cli/AGENTS.md | 8 +++----- cli/CLAUDE.md | 1 - cli/cmd/ibc/AGENTS.md | 6 ++---- docs/6-ibc-cli/tools/AGENTS.md | 10 ++++++---- docs/6-ibc-cli/tools/REFERENCE.md | 8 ++++---- e2e/AGENTS.md | 11 ++++++++--- e2e/internal/harness/AGENTS.md | 5 ++--- proto/AGENTS.md | 3 --- 8 files changed, 25 insertions(+), 27 deletions(-) delete mode 120000 cli/CLAUDE.md diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 2a365f794..19dc707db 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -4,13 +4,11 @@ - Run the relevant tests from this directory. Run `make lint` here when changing Go code or inputs that affect linting. -- From the repository root, keep `make -C e2e test` green when changing the CLI transport contract - exercised by the repository-wide black-box tests. +- When changing the CLI transport contract, run affected black-box tests from the repository root + with `make -C e2e test`, using `E2E_FLAGS` to select tests. Run the full suite for shared transport + changes that can affect multiple flows. ## Documentation generated from this code When changing commands or flags, configuration, cited behavior, or build inputs represented in the CLI reference pages, follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). - -Never hand-edit between a `` marker and its `END`: the -next run overwrites it. diff --git a/cli/CLAUDE.md b/cli/CLAUDE.md deleted file mode 120000 index 47dc3e3d8..000000000 --- a/cli/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/cli/cmd/ibc/AGENTS.md b/cli/cmd/ibc/AGENTS.md index 42905128b..ba24829fe 100644 --- a/cli/cmd/ibc/AGENTS.md +++ b/cli/cmd/ibc/AGENTS.md @@ -3,8 +3,6 @@ # CLI commands - Use the single `init()` in `main.go` to wire subcommands; do not add per-file `init()` functions. -- Define commands implemented in this package as variables with a `cmd*` prefix. Importable command - packages may construct command families whose transport types are shared outside this package. -- Package-local handlers use `func commandName(cmd *cobra.Command, args []string) error`. Importable - command packages may pass command-owned option structs to injected handlers. +- Define commands implemented in this package as variables with a `cmd*` prefix. +- Package-local handlers use `func commandName(cmd *cobra.Command, args []string) error`. - Put global flags such as `--home` and `--config` in `config.FlagSet`. diff --git a/docs/6-ibc-cli/tools/AGENTS.md b/docs/6-ibc-cli/tools/AGENTS.md index 738172aab..79e3ebe91 100644 --- a/docs/6-ibc-cli/tools/AGENTS.md +++ b/docs/6-ibc-cli/tools/AGENTS.md @@ -26,8 +26,9 @@ python3 docs/6-ibc-cli/tools/refgen.py all --check python3 docs/6-ibc-cli/tools/refgen.py all --plan ``` -Both commands build and run the CLI. The plan names anything that requires a decision. Read -[REFERENCE.md](REFERENCE.md) for the reported plan kinds and exit codes. +Both commands run the CLI, building it when needed. Resolve `--check` errors as well as plan entries: +`--plan` and `--report` omit notice-placement and prose-citation checks. Read +[REFERENCE.md](REFERENCE.md) for the reported kinds and exit codes. ## 2. Resolve decisions @@ -63,8 +64,9 @@ python3 docs/6-ibc-cli/tools/test-refgen-e2e.py When preparing a pull request, generate its documentation report with `python3 docs/6-ibc-cli/tools/refgen.py all --report` and identify any prose written by hand or work -handed back. The documentation work is complete when `--check` is clean or every outstanding item is -reported as blocked. +handed back. The documentation work is complete when affected prose has been reviewed and `--check` +is clean. If unresolved blockers remain, report the work as incomplete and list them using the +hand-back format in [REFERENCE.md](REFERENCE.md). Read [AUDIT.md](AUDIT.md) only when the task is to establish whether the generated pages are true, rather than whether they are current. diff --git a/docs/6-ibc-cli/tools/REFERENCE.md b/docs/6-ibc-cli/tools/REFERENCE.md index 516ced111..5f316047d 100644 --- a/docs/6-ibc-cli/tools/REFERENCE.md +++ b/docs/6-ibc-cli/tools/REFERENCE.md @@ -7,7 +7,9 @@ holds the rules; this one holds the detail you look up while following it. ## Plan entries -`--plan` classifies every gap. Each entry carries the file and line to go to. +`--plan` classifies generation gaps. Each entry carries the file and line to go to. +`--report` summarizes the same plan. Neither checks notice placement or prose citations; +resolve errors from `--check` as well as plan entries. | Kind | Meaning | What you do | |------|---------|-------------| @@ -17,8 +19,6 @@ holds the rules; this one holds the detail you look up while following it. | `curation` | a choice the source cannot express | step 2 | | `unreadable_method` | a method's body could not be located, so any rule inside it is invisible | teach `_body_brace` the new signature shape | | `nested_proto_type` | a proto declares a message or enum inside another; only top-level types are documented | move it to the top level, or decide where nested types belong on the page | -| `moved_citation` | a cited symbol is now declared in exactly one other file; the message names it | repoint, after confirming the sentence | -| `stale_citation` | a sentence in the prose cites a symbol that is gone, or was never there | see below | `--list-regions` prints just the ids of the stale regions, one per line — the list of prose sections to re-read once the tables are rewritten. @@ -112,7 +112,7 @@ Sentences outside the generated tables carry the code they came from: The path is from the repository root and is **required**; the symbol is a declaration in that file, and `Type.Member` must be that type's method or that struct's field. `--check` verifies all of this and refuses with `stale_citation` -otherwise. +otherwise. Citation errors appear in `--check` output, not in `--plan` or `--report`. A path is the one derived fact left in a citation, so a move is answered rather than merely refused. When the cited path no longer resolves but the symbol is diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index da57e58fb..d31367a42 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -2,13 +2,18 @@ # E2E tests -Read [README.md](README.md) for running tests, environment behavior, matrix commands, and cleanup. +Read the relevant sections of [README.md](README.md) before running tests, changing requirements or +topology, or diagnosing environment or cleanup behavior. - Acceptance tests use `internal/e2etest` environments and assert through route-bound application bindings. Hold the temporary IBC CLI driver and relayer explicitly. Transport-contract tests may call the concrete driver or relayer directly. -- Use the IBC CLI's public command transport types, generated RPC clients, and signer-keyfile package for - transport and provisioning. Do not import `cli/internal` or invoke handlers in process. +- Application-effect wait budgets derive from the resolved Chain's `environment.Timing`, never from a + literal tuned to instant Anvil. Test-application effect and stability observation lives with the + e2e-only bindings that interpret those effects. +- Exercise CLI commands through the binary's public input/output contracts. Use generated RPC clients + and `cli/keyfile` for RPC and signer provisioning. Do not import `cli/internal` or invoke handlers + in process. - Declare test requirements and regenerate and check the matrix after changing requirements or topology. - Preserve inner quotes in `E2E_FLAGS`, because Make expands it into a shell command: `make -C e2e test E2E_FLAGS="-run '^(TestA|TestB)' -count=1"`. diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index f9d84cec4..a46d48aa1 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -2,11 +2,10 @@ # E2E harness -- Chain transaction and application-effect wait budgets derive from the resolved Chain's +- Chain transaction wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned to instant Anvil. Provider and process startup and shutdown use separate lifecycle deadlines. Launch-side readiness uses - `chain/evm/poll.Until`; test-application effect and stability observation lives with the e2e-only - bindings that interpret those effects. + `chain/evm/poll.Until`. - **Docker discipline.** Containers/networks carry the `ibc-cli-e2e=true` and `ibc-cli-run=` labels and the `ibc-cli-e2e-` name prefix, with pinned images. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt diff --git a/proto/AGENTS.md b/proto/AGENTS.md index 3a98f7404..08c0deaaa 100644 --- a/proto/AGENTS.md +++ b/proto/AGENTS.md @@ -7,6 +7,3 @@ When changing schemas under `proto/cli/` or their generation configuration, run When changing the public API under `proto/cli/`, follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). - -Never hand-edit between a `` marker and its `END`: the -next run overwrites it. From c71b78d46fba818c8813278f52805d8224da4f0f Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 15:31:23 +0200 Subject: [PATCH 4/9] docs: apply AGENTS.md review decisions Replace the CLI test imperatives with facts about the module and e2e execution modes, trim the CLI command conventions to the two that are not visible in the code, map the e2e README pointer to named sections, replace harness literals with the helpers that define them, drop the compile-enforced import prohibition, and align the proto regeneration wording between the server and proto files. Signed-off-by: Gjermund Garaba --- cli/AGENTS.md | 10 +++++----- cli/cmd/ibc/AGENTS.md | 8 ++++---- cli/internal/server/AGENTS.md | 5 +++-- e2e/AGENTS.md | 17 ++++++++++------- e2e/internal/harness/AGENTS.md | 5 +++-- 5 files changed, 25 insertions(+), 20 deletions(-) diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 19dc707db..eca532358 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -2,11 +2,11 @@ # IBC CLI -- Run the relevant tests from this directory. Run `make lint` here when changing Go code or inputs - that affect linting. -- When changing the CLI transport contract, run affected black-box tests from the repository root - with `make -C e2e test`, using `E2E_FLAGS` to select tests. Run the full suite for shared transport - changes that can affect multiple flows. +- `cli/` is its own Go module. Run `make lint` here when changing Go code or inputs that affect + linting. +- Black-box tests for the CLI transport contract run from the repository root with + `make -C e2e test`, using `E2E_FLAGS` to select tests. The default `E2E_MODE=fast` skips tests + that require Besu; `E2E_MODE=complete` runs them. ## Documentation generated from this code diff --git a/cli/cmd/ibc/AGENTS.md b/cli/cmd/ibc/AGENTS.md index ba24829fe..b0afd78b3 100644 --- a/cli/cmd/ibc/AGENTS.md +++ b/cli/cmd/ibc/AGENTS.md @@ -2,7 +2,7 @@ # CLI commands -- Use the single `init()` in `main.go` to wire subcommands; do not add per-file `init()` functions. -- Define commands implemented in this package as variables with a `cmd*` prefix. -- Package-local handlers use `func commandName(cmd *cobra.Command, args []string) error`. -- Put global flags such as `--home` and `--config` in `config.FlagSet`. +- Use the single `init()` in `main.go` to wire `cmd*` subcommands; do not add per-file `init()` + functions. +- Put global flags such as `--home` and `--config` in `config.FlagSet`, registered by + `config.DeclarePersistentFlags`. diff --git a/cli/internal/server/AGENTS.md b/cli/internal/server/AGENTS.md index c3e901661..b6afb3f5d 100644 --- a/cli/internal/server/AGENTS.md +++ b/cli/internal/server/AGENTS.md @@ -5,5 +5,6 @@ Keep this package as a transport adapter: convert ConnectRPC/proto types to service DTOs, call the service interface, and map domain errors to `connect.Code*`. -When an RPC schema changes, update `proto/cli/` and run `make codegen-proto` from `cli/` before -updating the handler. Run `make codegen-mocks` from `cli/` when an affected mocked interface changes. +When an RPC schema changes, update `proto/cli/`, run `make -C cli codegen-proto` from the repository +root, and include the updated bindings in `cli/api/v2/` before updating the handler. Run +`make -C cli codegen-mocks` from the repository root when an affected mocked interface changes. diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index d31367a42..a0f50b456 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -2,18 +2,21 @@ # E2E tests -Read the relevant sections of [README.md](README.md) before running tests, changing requirements or -topology, or diagnosing environment or cleanup behavior. +Read the relevant [README.md](README.md) section first: +[Running the acceptance tests](README.md#running-the-acceptance-tests) before running tests, +[Writing a test](README.md#writing-a-test) before adding one, +[Provider and topology matrix](README.md#provider-and-topology-matrix) before changing requirements +or topology, and [Debugging](README.md#debugging) for environment or cleanup behavior. -- Acceptance tests use `internal/e2etest` environments and assert through route-bound application - bindings. Hold the temporary IBC CLI driver and relayer explicitly. Transport-contract tests may - call the concrete driver or relayer directly. +- Acceptance tests follow the explicit setup sequence in "Writing a test": `e2etest.Start`, + `e2etest.Deploy` (which returns the driver), app constructors such as `e2etest.NewTransfer`, and + `e2etest.StartRelayer`, asserting through the app values. Transport-contract tests may call the + concrete driver or relayer directly. - Application-effect wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned to instant Anvil. Test-application effect and stability observation lives with the e2e-only bindings that interpret those effects. - Exercise CLI commands through the binary's public input/output contracts. Use generated RPC clients - and `cli/keyfile` for RPC and signer provisioning. Do not import `cli/internal` or invoke handlers - in process. + and `cli/keyfile` for RPC and signer provisioning. - Declare test requirements and regenerate and check the matrix after changing requirements or topology. - Preserve inner quotes in `E2E_FLAGS`, because Make expands it into a shell command: `make -C e2e test E2E_FLAGS="-run '^(TestA|TestB)' -count=1"`. diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index a46d48aa1..c0a1732d2 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -6,8 +6,9 @@ `environment.Timing`, never from a literal tuned to instant Anvil. Provider and process startup and shutdown use separate lifecycle deadlines. Launch-side readiness uses `chain/evm/poll.Until`. -- **Docker discipline.** Containers/networks carry the `ibc-cli-e2e=true` and - `ibc-cli-run=` labels and the `ibc-cli-e2e-` name prefix, with pinned images. Anvil runs +- **Docker discipline.** Containers/networks carry the labels from + `chain/evm/container.Labels(runID)` and names from + `chain/evm/container.NamePrefix(runID, chainID)`, with pinned images. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt instead of waiting out the kill grace). Don't reintroduce a shell-wrapped entrypoint. StopNode/StartNode fault injection is docker pause/unpause; chain state stays in memory. From 21efdd029dfd5506c8fb230db93606a79f1ac5a2 Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 15:43:41 +0200 Subject: [PATCH 5/9] docs: close the gaps found in the AGENTS.md review Point the root file at nested area guidance so Codex sessions started at the repository root find it, state the repo-wide facts an agent cannot infer (Go module boundaries, SPDX lint targets, aggregate check target, disposable Docker containers), move the mock regeneration rule to the CLI scope where every mocked interface is covered, name the e2e matrix targets, state the Postgres test gate once, fold the compiler-enforced two-backend line into the Repository bullet, and delete the unreferenced cli/CONTEXT.md glossary. Signed-off-by: Gjermund Garaba --- AGENTS.md | 7 ++++++ cli/AGENTS.md | 2 ++ cli/CONTEXT.md | 45 ----------------------------------- cli/internal/server/AGENTS.md | 3 +-- cli/internal/store/AGENTS.md | 10 ++++---- e2e/AGENTS.md | 4 +++- 6 files changed, 18 insertions(+), 53 deletions(-) delete mode 100644 cli/CONTEXT.md diff --git a/AGENTS.md b/AGENTS.md index 984f99320..5ce0c018f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,14 @@ # Repository guidance +- Nested `AGENTS.md` files hold area guidance. Before changing files under a directory, read each + `AGENTS.md` between that directory and this one. +- `cli/`, `e2e/`, and `gen/go/solidity-abi/` are separate Go modules. - `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, except `gen/README.md`, which documents the tree. - Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. +- New files need an SPDX header; `make lint-license` checks them and `make lint-fix-license` adds + them. `make run-all-checks` runs the CLI, e2e, generated-code, and license checks together. +- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun them + without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. diff --git a/cli/AGENTS.md b/cli/AGENTS.md index eca532358..3b811c64f 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -4,6 +4,8 @@ - `cli/` is its own Go module. Run `make lint` here when changing Go code or inputs that affect linting. +- Interfaces listed in `.mockery.yaml` have generated mocks. After changing one, run + `make codegen-mocks` from `cli/`; CI does not regenerate them. - Black-box tests for the CLI transport contract run from the repository root with `make -C e2e test`, using `E2E_FLAGS` to select tests. The default `E2E_MODE=fast` skips tests that require Besu; `E2E_MODE=complete` runs them. diff --git a/cli/CONTEXT.md b/cli/CONTEXT.md deleted file mode 100644 index abdad7b72..000000000 --- a/cli/CONTEXT.md +++ /dev/null @@ -1,45 +0,0 @@ - - -# IBC CLI Environment - -The IBC CLI environment context describes the on-chain protocol topology and off-chain actors that a test declares and obtains as a ready Environment. - -## Language - -**Environment Spec**: -A declaration of the Chains, IBC Instances, IBC Connections, Attestors, and Relayers a test requires. It describes desired resources rather than their ready state. - -**Environment**: -The realized, ready set of resources declared by an Environment Spec. It is the lifecycle boundary through which a test accesses those resources. - -**Realization**: -The process by which an Environment Spec becomes an Environment, satisfying each declaration with a newly created or already-existing resource. - -**Chain**: -A blockchain network that hosts zero or more IBC Instances. - -**IBC Instance**: -An installation of the IBC protocol hosted on a Chain. An IBC Instance may be newly created or already exist. -_Avoid_: Deployment - -**IBC Client**: -One end of an IBC Connection, hosted by an IBC Instance and tracking the counterparty. Its counterparty client identifier points to the reciprocal IBC Client. - -**IBC Connection**: -The IBC protocol relationship between two IBC Instances, constituted by a reciprocal pair of IBC Clients. -_Avoid_: Route as a synonym for an IBC Connection - -**Attestor**: -An independent logical actor configured to serve a particular IBC Client. Its identity is independent of process or endpoint placement. - -**Relayer**: -An independent logical actor that relays protocol messages for one or more IBC Connections. Its identity is independent of process or endpoint placement, and multiple Relayers may serve the same IBC Connection. - -**Relayer Route**: -A directed configuration belonging to a Relayer when it needs to carry messages in one direction over an IBC Connection. It is not an independent Environment resource and does not replace the Connection. - -**Test Application**: -A test-only application deployed on a Chain to originate protocol traffic or expose observable state. It is explicit test setup, not an Environment resource. - -**Test Application Binding**: -A typed, non-owning test-side handle to the source and destination contracts used by one application on a directed synthetic route. It hides application ABI and RPC mechanics but does not own lifecycle, relayer state, or cross-resource orchestration. diff --git a/cli/internal/server/AGENTS.md b/cli/internal/server/AGENTS.md index b6afb3f5d..b9fa5400c 100644 --- a/cli/internal/server/AGENTS.md +++ b/cli/internal/server/AGENTS.md @@ -6,5 +6,4 @@ Keep this package as a transport adapter: convert ConnectRPC/proto types to serv service interface, and map domain errors to `connect.Code*`. When an RPC schema changes, update `proto/cli/`, run `make -C cli codegen-proto` from the repository -root, and include the updated bindings in `cli/api/v2/` before updating the handler. Run -`make -C cli codegen-mocks` from the repository root when an affected mocked interface changes. +root, and include the updated bindings in `cli/api/v2/` before updating the handler. diff --git a/cli/internal/store/AGENTS.md b/cli/internal/store/AGENTS.md index 3cbf57cc1..fd948b9fe 100644 --- a/cli/internal/store/AGENTS.md +++ b/cli/internal/store/AGENTS.md @@ -7,12 +7,12 @@ - From `cli/`, create paired migrations with `go run scripts/migratenew.go `. Edit both `migrations/sqlite/` and `migrations/postgres/`; keep their behavior equivalent while using each dialect's syntax. -- For persistence or schema changes, run the relevant tests against both SQLite and PostgreSQL - from `cli/`, with `TEST_POSTGRES=true` and Docker available. PostgreSQL is skipped unless - `TEST_POSTGRES=true`. Report any backend you could not verify. +- For persistence or schema changes, test against both backends from `cli/`. PostgreSQL tests are + skipped unless `TEST_POSTGRES=true` and Docker is available. Report any backend you could not + verify. - Write shared queries in `queries/` with sqlc arguments such as `sqlc.arg` and `sqlc.narg`, then run `make codegen-sql` from `cli/`. - Don't edit generated files in `repository/sqlite` or `repository/postgres`. -- Add public persistence methods to the `Repository` interface in `store.go`. -- Implement every method in both `store_sqlite.go` and `store_postgres.go`. +- Add public persistence methods to the `Repository` interface in `store.go`, implemented in both + `store_sqlite.go` and `store_postgres.go`. - Return domain structs from `store.go`, not generated sqlc row types. diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index a0f50b456..4a066d222 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -17,6 +17,8 @@ or topology, and [Debugging](README.md#debugging) for environment or cleanup beh e2e-only bindings that interpret those effects. - Exercise CLI commands through the binary's public input/output contracts. Use generated RPC clients and `cli/keyfile` for RPC and signer provisioning. -- Declare test requirements and regenerate and check the matrix after changing requirements or topology. +- Declare test requirements in `e2etest.EVMRequirements`, naming a provider only when the test + depends on it. After changing requirements or topology, run `make -C e2e generate-matrix` and + `make -C e2e check-matrix`; `make -C e2e test` does not check the matrix. - Preserve inner quotes in `E2E_FLAGS`, because Make expands it into a shell command: `make -C e2e test E2E_FLAGS="-run '^(TestA|TestB)' -count=1"`. From ac8e0e682a4faaed6539f6a16e4c97adba49e296 Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 17:18:32 +0200 Subject: [PATCH 6/9] docs: trim AGENTS.md guidance agents can find on their own Remove facts that the code, generated-file headers, Makefiles, or the adjacent README already state where an agent would meet them: the CLI command conventions documented in main.go, the server codegen paragraph duplicated in proto/, the module inventory, the sqlc and refgen prerequisites, the generated-page marker warning, the e2e setup sequence shown in the README, and helper names visible in the providers. Keep what is silent when wrong: the fast-mode Besu skip, the mock regeneration CI does not run, the matrix check the test target does not run, the container labels cleanup depends on, and the Repository placement the compiler does not check. Correct the README sentence on provider requirements that the cut e2e clause had been patching. Signed-off-by: Gjermund Garaba --- AGENTS.md | 4 +--- cli/AGENTS.md | 8 +++----- cli/cmd/ibc/AGENTS.md | 8 -------- cli/internal/server/AGENTS.md | 3 --- cli/internal/store/AGENTS.md | 8 +++----- docs/6-ibc-cli/tools/AGENTS.md | 10 +++------- e2e/AGENTS.md | 14 ++++---------- e2e/README.md | 3 ++- e2e/internal/harness/AGENTS.md | 18 ++++++++---------- 9 files changed, 24 insertions(+), 52 deletions(-) delete mode 100644 cli/cmd/ibc/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 5ce0c018f..2b89ffe1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,12 +4,10 @@ - Nested `AGENTS.md` files hold area guidance. Before changing files under a directory, read each `AGENTS.md` between that directory and this one. -- `cli/`, `e2e/`, and `gen/go/solidity-abi/` are separate Go modules. - `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, except `gen/README.md`, which documents the tree. - Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. -- New files need an SPDX header; `make lint-license` checks them and `make lint-fix-license` adds - them. `make run-all-checks` runs the CLI, e2e, generated-code, and license checks together. +- New files need the SPDX header; `make lint-license` checks it. - Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun them without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 3b811c64f..0a3fe0d66 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -2,13 +2,11 @@ # IBC CLI -- `cli/` is its own Go module. Run `make lint` here when changing Go code or inputs that affect - linting. - Interfaces listed in `.mockery.yaml` have generated mocks. After changing one, run `make codegen-mocks` from `cli/`; CI does not regenerate them. -- Black-box tests for the CLI transport contract run from the repository root with - `make -C e2e test`, using `E2E_FLAGS` to select tests. The default `E2E_MODE=fast` skips tests - that require Besu; `E2E_MODE=complete` runs them. +- `make -C e2e test` defaults to `E2E_MODE=fast`, which skips tests that require Besu without + failing; `E2E_MODE=complete` runs them. See + [Running the acceptance tests](../e2e/README.md#running-the-acceptance-tests). ## Documentation generated from this code diff --git a/cli/cmd/ibc/AGENTS.md b/cli/cmd/ibc/AGENTS.md deleted file mode 100644 index b0afd78b3..000000000 --- a/cli/cmd/ibc/AGENTS.md +++ /dev/null @@ -1,8 +0,0 @@ - - -# CLI commands - -- Use the single `init()` in `main.go` to wire `cmd*` subcommands; do not add per-file `init()` - functions. -- Put global flags such as `--home` and `--config` in `config.FlagSet`, registered by - `config.DeclarePersistentFlags`. diff --git a/cli/internal/server/AGENTS.md b/cli/internal/server/AGENTS.md index b9fa5400c..74b63d16d 100644 --- a/cli/internal/server/AGENTS.md +++ b/cli/internal/server/AGENTS.md @@ -4,6 +4,3 @@ Keep this package as a transport adapter: convert ConnectRPC/proto types to service DTOs, call the service interface, and map domain errors to `connect.Code*`. - -When an RPC schema changes, update `proto/cli/`, run `make -C cli codegen-proto` from the repository -root, and include the updated bindings in `cli/api/v2/` before updating the handler. diff --git a/cli/internal/store/AGENTS.md b/cli/internal/store/AGENTS.md index fd948b9fe..787dd770c 100644 --- a/cli/internal/store/AGENTS.md +++ b/cli/internal/store/AGENTS.md @@ -10,9 +10,7 @@ - For persistence or schema changes, test against both backends from `cli/`. PostgreSQL tests are skipped unless `TEST_POSTGRES=true` and Docker is available. Report any backend you could not verify. -- Write shared queries in `queries/` with sqlc arguments such as `sqlc.arg` and `sqlc.narg`, then run - `make codegen-sql` from `cli/`. -- Don't edit generated files in `repository/sqlite` or `repository/postgres`. -- Add public persistence methods to the `Repository` interface in `store.go`, implemented in both - `store_sqlite.go` and `store_postgres.go`. +- `queries/` is shared by both dialects: write portable SQL with `sqlc.arg` and `sqlc.narg`, then + run `make codegen-sql` from `cli/`. +- Add public persistence methods to the `Repository` interface in `store.go`, not to `Store`. - Return domain structs from `store.go`, not generated sqlc row types. diff --git a/docs/6-ibc-cli/tools/AGENTS.md b/docs/6-ibc-cli/tools/AGENTS.md index 79e3ebe91..5ea1ca7c5 100644 --- a/docs/6-ibc-cli/tools/AGENTS.md +++ b/docs/6-ibc-cli/tools/AGENTS.md @@ -14,10 +14,8 @@ The generated pages are: | [6-cli-commands.md](../6-cli-commands.md) | the built command tree | | [7-api.md](../7-api.md) | `proto/cli/*.proto` | -Run the commands below from the repository root. They require Python, Go, and `buf`. - -Never edit between a `` marker and its `END`. To change the generated example -configuration, edit `cli/internal/config/testdata/sample.yml`. +Run the commands below from the repository root. To change the generated example configuration, +edit `cli/internal/config/testdata/sample.yml`. ## 1. Find what moved @@ -26,9 +24,7 @@ python3 docs/6-ibc-cli/tools/refgen.py all --check python3 docs/6-ibc-cli/tools/refgen.py all --plan ``` -Both commands run the CLI, building it when needed. Resolve `--check` errors as well as plan entries: -`--plan` and `--report` omit notice-placement and prose-citation checks. Read -[REFERENCE.md](REFERENCE.md) for the reported kinds and exit codes. +Read [REFERENCE.md](REFERENCE.md) for the reported kinds and exit codes. ## 2. Resolve decisions diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index 4a066d222..e4dc910e4 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -8,17 +8,11 @@ Read the relevant [README.md](README.md) section first: [Provider and topology matrix](README.md#provider-and-topology-matrix) before changing requirements or topology, and [Debugging](README.md#debugging) for environment or cleanup behavior. -- Acceptance tests follow the explicit setup sequence in "Writing a test": `e2etest.Start`, - `e2etest.Deploy` (which returns the driver), app constructors such as `e2etest.NewTransfer`, and - `e2etest.StartRelayer`, asserting through the app values. Transport-contract tests may call the - concrete driver or relayer directly. +- Transport-contract tests may call the concrete driver or relayer directly; acceptance tests follow + the sequence in "Writing a test". - Application-effect wait budgets derive from the resolved Chain's `environment.Timing`, never from a - literal tuned to instant Anvil. Test-application effect and stability observation lives with the - e2e-only bindings that interpret those effects. -- Exercise CLI commands through the binary's public input/output contracts. Use generated RPC clients - and `cli/keyfile` for RPC and signer provisioning. -- Declare test requirements in `e2etest.EVMRequirements`, naming a provider only when the test - depends on it. After changing requirements or topology, run `make -C e2e generate-matrix` and + literal tuned to instant Anvil. +- After changing requirements or topology, run `make -C e2e generate-matrix` and `make -C e2e check-matrix`; `make -C e2e test` does not check the matrix. - Preserve inner quotes in `E2E_FLAGS`, because Make expands it into a shell command: `make -C e2e test E2E_FLAGS="-run '^(TestA|TestB)' -count=1"`. diff --git a/e2e/README.md b/e2e/README.md index 2883d6d77..d00a7e08c 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -87,7 +87,8 @@ func TestTransfer_AutoRelay(t *testing.T) { `e2etest.NewSigner` creates an independent identity; tests create one per role and pass them explicitly — `Deploy` takes the deployer and relayer signers, the app constructors take the sender (the signer that deployed the apps). Managed Chains fund them through their resolved funding capability; an attached Chain must fund the public addresses out of band before `Deploy`. Credentials are written only to protected temporary signer files referenced by alias in the temporary IBC CLI configuration. -Declare capabilities instead of naming a provider. For example, a controlled-mining test uses: +Declare capabilities, naming a provider only when the test depends on it. For example, a +controlled-mining test uses: ```go chains := e2etest.EVMChains(t, e2etest.EVMRequirements{ControlledMining: true}, diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index c0a1732d2..d11f2ff88 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -2,13 +2,11 @@ # E2E harness -- Chain transaction wait budgets derive from the resolved Chain's - `environment.Timing`, never from a literal tuned to instant Anvil. Provider and process startup - and shutdown use separate lifecycle deadlines. Launch-side readiness uses - `chain/evm/poll.Until`. -- **Docker discipline.** Containers/networks carry the labels from - `chain/evm/container.Labels(runID)` and names from - `chain/evm/container.NamePrefix(runID, chainID)`, with pinned images. Anvil runs - with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt - instead of waiting out the kill grace). Don't reintroduce a shell-wrapped entrypoint. - StopNode/StartNode fault injection is docker pause/unpause; chain state stays in memory. +- Chain transaction wait budgets derive from the resolved Chain's `environment.Timing`, never from + a literal tuned to instant Anvil. Provider and process startup and shutdown use separate lifecycle + deadlines. +- **Docker discipline.** Containers carry `chain/evm/container.Labels` so `e2e/scripts/clean.sh` can + find them. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and + shutdown is prompt instead of waiting out the kill grace). Don't reintroduce a shell-wrapped + entrypoint. StopNode/StartNode fault injection is docker pause/unpause; chain state stays in + memory. From 21892b8b6d1d03f659acccf589fd7f9425f38bbb Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 17:22:42 +0200 Subject: [PATCH 7/9] little cleanly Signed-off-by: Gjermund Garaba --- e2e/AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index e4dc910e4..e20dc3750 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -3,10 +3,10 @@ # E2E tests Read the relevant [README.md](README.md) section first: -[Running the acceptance tests](README.md#running-the-acceptance-tests) before running tests, -[Writing a test](README.md#writing-a-test) before adding one, -[Provider and topology matrix](README.md#provider-and-topology-matrix) before changing requirements -or topology, and [Debugging](README.md#debugging) for environment or cleanup behavior. +- [Running the acceptance tests](README.md#running-the-acceptance-tests) before running tests +- [Writing a test](README.md#writing-a-test) before adding one, +- [Provider and topology matrix](README.md#provider-and-topology-matrix) before changing requirements or topology +- [Debugging](README.md#debugging) for environment or cleanup behavior. - Transport-contract tests may call the concrete driver or relayer directly; acceptance tests follow the sequence in "Writing a test". From b0ffb30639fb507e3815efe45959dda319778f9a Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Wed, 21 Oct 2026 17:35:07 +0200 Subject: [PATCH 8/9] little cleanly Signed-off-by: Gjermund Garaba --- AGENTS.md | 12 ++++-------- e2e/internal/harness/AGENTS.md | 10 ++-------- 2 files changed, 6 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b89ffe1c..fedf2c85d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,12 +2,8 @@ # Repository guidance -- Nested `AGENTS.md` files hold area guidance. Before changing files under a directory, read each - `AGENTS.md` between that directory and this one. -- `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, - except `gen/README.md`, which documents the tree. -- Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their - output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. +- Nested `AGENTS.md` files hold area guidance. Before changing files under a directory, read each `AGENTS.md` between that directory and this one. +- `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, except `gen/README.md`, which documents the tree. +- Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. - New files need the SPDX header; `make lint-license` checks it. -- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun them - without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. +- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun the without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index d11f2ff88..bcfaff37f 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -2,11 +2,5 @@ # E2E harness -- Chain transaction wait budgets derive from the resolved Chain's `environment.Timing`, never from - a literal tuned to instant Anvil. Provider and process startup and shutdown use separate lifecycle - deadlines. -- **Docker discipline.** Containers carry `chain/evm/container.Labels` so `e2e/scripts/clean.sh` can - find them. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and - shutdown is prompt instead of waiting out the kill grace). Don't reintroduce a shell-wrapped - entrypoint. StopNode/StartNode fault injection is docker pause/unpause; chain state stays in - memory. +- Chain transaction wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned to instant Anvil. Provider and process startup and shutdown use separate lifecycle deadlines. +- **Docker discipline.** Containers carry `chain/evm/container.Labels` so `e2e/scripts/clean.sh` can find them. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt instead of waiting out the kill grace). Don't reintroduce a shell-wrapped entrypoint. StopNode/StartNode fault injection is docker pause/unpause; chain state stays in memory. From e29a5b374b8f8bfd187b1b47796e51fb053bc209 Mon Sep 17 00:00:00 2001 From: Gjermund Garaba Date: Mon, 26 Oct 2026 17:07:19 +0100 Subject: [PATCH 9/9] docs: say Postgres tests fail without Docker once enabled GuardPostgresTests checks only TEST_POSTGRES; NewPostgresContainer then requires Docker and fails the run rather than skipping it. Also fix a typo in the root permission line. Signed-off-by: Gjermund Garaba --- AGENTS.md | 2 +- cli/internal/store/AGENTS.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fedf2c85d..468e3f977 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,4 +6,4 @@ - `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, except `gen/README.md`, which documents the tree. - Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. - New files need the SPDX header; `make lint-license` checks it. -- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun the without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. +- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun them without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. diff --git a/cli/internal/store/AGENTS.md b/cli/internal/store/AGENTS.md index 787dd770c..386c541b0 100644 --- a/cli/internal/store/AGENTS.md +++ b/cli/internal/store/AGENTS.md @@ -8,8 +8,8 @@ `migrations/sqlite/` and `migrations/postgres/`; keep their behavior equivalent while using each dialect's syntax. - For persistence or schema changes, test against both backends from `cli/`. PostgreSQL tests are - skipped unless `TEST_POSTGRES=true` and Docker is available. Report any backend you could not - verify. + skipped unless `TEST_POSTGRES=true`; enabled tests require working Docker. Report any backend + you could not verify. - `queries/` is shared by both dialects: write portable SQL with `sqlc.arg` and `sqlc.narg`, then run `make codegen-sql` from `cli/`. - Add public persistence methods to the `Repository` interface in `store.go`, not to `Store`.