Repository navigation
docs: add EGM README contracts for every code directory - #128
Conversation
Add a README.md contract to each code directory: adapters, state, internal, examples, and scripts. Each one has Overview, Interface, Invariants, Side Effects, and Verification sections that cite the source as [file:symbol]. Directories without Go files get a short index of their children. Add a repository blueprint to the root README, before "Status": the dispatch steps, the root package's exported symbols and rules, links to each child contract, cross-package rules and side effects, and the test commands. Existing README text is kept. The one change to it fixes a broken tutorial anchor in the Linear example. _Generated with `xum` • Model: `anthropic:claude-opus-5-5` • Thinking: `xhigh`_
|
@codex review |
|
@codex security review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0ab9ff4324
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- Root README: deferred dispatch starts the handler before the adapter acknowledges, so the two run at the same time; lease renewal happens only under deferred dispatch and burst batches. - adapters/slack and internal/ratelimit: the deadline-bounded retry keeps the backoff sleep inside the ack window, but not the HTTP attempts. - slackapi: limit the POST-to-BaseURL side effect to Call and the typed Web API methods, and document the small-limit SplitMarkdown exception. - State examples: the deferred bot.Shutdown closes the state client through State.Shutdown. _Generated with `xum` • Model: `anthropic:claude-opus-5-5` • Thinking: `xhigh`_
|
@codex review |
|
@codex security review |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 16dcdfcd69
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- slackapi: a throttling response ends in *RateLimited, not *APIError. - Root README: ctx bounds the Shutdown waits, so adapters and State can shut down while deferred work or listeners still run. - Adapters and root README: InstallStore.Lookup runs only for deliveries routed to an install and for calls that need a token, not for every webhook. _Generated with `xum` • Model: `anthropic:claude-opus-5-5` • Thinking: `xhigh`_
|
@codex review |
|
@codex security review |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb84b59532
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Retry returns *RateLimited only when the retry policy or the deadline check stops it. A context cancelled during a backoff sleep returns the context error, and a failed HTTP attempt returns its transport error. Say so in the adapters index, the root README, and the slackapi and Linear retry rules. _Generated with `xum` • Model: `anthropic:claude-opus-5-5` • Thinking: `xhigh`_
|
@codex review |
|
@codex security review |
|
Codex Review: Didn't find any major issues. Keep them coming! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
|
Delivery record for this PR:
Generated with |
Adds a README contract to every code directory, and a repository blueprint to the root README, so contributors and coding agents can find each package's interface, rules, and side effects without reading all the source. This is a docs-only change: no
.go,go.mod, or config file changes.What changes
adapters/,state/,internal/,examples/, andscripts/. Each package README has Overview, Interface, Invariants, Side Effects, and Verification sections, and cites its source as[file:symbol]. Directories without Go files get a short index of their children.## Status. It covers the 8 dispatch steps, the root package's exported symbols and rules, links to each child README, cross-package rules and side effects, and the test commands.#step-5-expose-the-bot-to-slack, which does not exist. It now links to#use-http-instead-of-socket-modein the Slack tutorial.The diff adds 2,021 lines and removes 1 across 22 files. Each README stands alone, so you can review them one at a time.
How the content was checked
Follow-ups (not in this PR)
The review also found these. This PR documents the current behavior and does not change any code:
state/redisExtendLockwith a TTL under 1 ms deletes the lock and returnstrue. Reproduced on Redis 7.2.adapters/linearnever refreshes a token whose response has noexpires_in.adapters/linear/raw.go.Validation
go vet ./...passes in all 7 modules.GOFLAGS=-race go test -count=1 ./...passes in all 7 modules. This includesdocumentation_test.go, which builds the README's<!-- build -->snippet and checks its key phrases. The Postgres and Redis tests ran against Testcontainers.mise run testandmise run vetfail before any test runs because of a local Go toolchain mismatch. So I ran each task's commands directly with Go 1.26.10. CI runs the pinned and minimum Go legs.Generated with
xum• Model:anthropic:claude-opus-5-5• Thinking:xhigh