gitk-go: Instructions file for Codex

Automation Notes

This project occasionally uses AI assistance. To keep contributions consistent, agents should follow these rules:

1. Keep UI logic testable. Add pure helpers near their owner and cover them with unit tests.
2. Treat cmd and internal/gui as UI orchestration layers. Core Git behavior belongs in internal/git.
3. Use go test ./..., go fmt, and go vet ./... before sending changes whenever the environment allows it.
4. README and AGENTS should stay ASCII-only and concise.
5. Keep lines under 120 characters (enforced by golangci-lint).
6. If a function returns multiple values of the same type, use named return values.
7. Dot imports are only allowed for modernc.org/tk9.0.
8. Describe sandbox or permission issues observed while running commands so maintainers can reproduce locally, but ignore nice(5) failed: operation not permitted.
9. Keep GUI assets (icons, images, etc.) inside internal/gui/assets and reference them there when using go:embed.
10. Group related controller/state fields into dedicated structs instead of leaving long flat structs.
11. When working with mutexes, prefer defer mu.Unlock() immediately after locking unless there is a strong reason not to.
12. Prefer slog/log instead of log for logging.
13. Prefer tests co-located with the implementation (e.g. internal/gui/filter_test.go for filter.go) instead of creating per-feature test filenames.
14. Always run tests with GOCACHE set to avoid sandbox issues: env GOCACHE="$PWD/.gocache" go test ./....
15. Avoid abstraction-only wrappers. Add methods when they encode behavior, enforce invariants, or coordinate multiple fields. Prefer package functions over methods when no receiver state is used.
16. Keep Tk widget construction, bindings, tag names, dialogs, menu setup, and widget guards in internal/gui/view.
17. Keep controller code focused on service calls, async scheduling, persistence, status text, and model/view coordination. Do not leave direct widget field checks in controllers when a view helper can own them.
18. Keep pure state transitions, selection policy, diff view models, and display preparation in internal/gui/model.
19. Do not duplicate constants or helpers across internal/gui, model, and view; promote one owner instead.
20. Prefer typed modernc.org/tk9.0 APIs over tkutil.Evalf. Use Evalf only when the wrapper lacks the needed Tk subcommand or behavior.
21. Do not remove an Evalf workaround or XXX comment by inspection alone. Reproduce the GUI path or add focused coverage that proves the replacement behaves the same.
22. Keep unavoidable Evalf calls narrow and documented at the call site, including why the typed wrapper is not sufficient.
23. Do not amend or rewrite existing commits unless the user explicitly asks for history rewriting.
24. Model-owned maps should be initialized by their state constructors when nil does not represent a real lifecycle state. Tests should use those constructors instead of relying on raw zero values.
25. Required Tk widget assumptions only hold after view.App.Build. Startup code may activate themes before build, but widget-specific style refreshes must run after widgets are constructed.
26. Treat initialized commit entries as value data. git.Entry should own a git.Commit value, and GUI/model collections should use []git.Entry unless nil is a real lifecycle state.
27. Keep backend stream internals pointer-based when useful, but reject nil commits at the service boundary before creating entries. Model helpers should use hash/index validity checks for recoverable missing-row cases.
28. Do not add helper functions that only restate direct field access, such as wrapping entry.Commit.Hash, unless they enforce an invariant or coordinate more than one field.