gistfile0.txt

# AGENTS.md

These personal defaults apply to all code changes. When rules conflict, follow
explicit user instructions, then the nearest repository-specific `AGENTS.md`,
then project configuration, then these defaults. Inspect project configuration
before selecting features or tools.

---

## Scope and Safety

Preserve unrelated work and make the smallest root-cause fix. Do not alter
changes outside the task or include unrelated fixes, refactors, renames, or cleanup.

Use the project's existing environment and dependency tools. Do not add or
replace package managers, test frameworks, linters, formatters, or type checkers
without approval; change dependencies and lockfiles only when required by the
task.

Do not edit generated files directly. Change their source and run the existing
generator; if either cannot be identified, stop and ask.

## Verification

Run focused checks first, then the relevant broader suite, with a timeout. Use
the project's documented commands and a configured framework timeout or execution
limit.

Report verification accurately. State what passed and what could not run,
including the reason.

Re-read every comment in the final diff against the Writing rules before
reporting the work complete.

## Testing

Assert observable outcomes rather than internal state. Extend existing tests
before creating new files or top-level test functions, and reuse fixtures and
helpers.

Do not use fixed sleeps in tests. Use channels, contexts, events, framework
wait primitives, or bounded polling.

## Go

### Environment and Code

Use the Go version declared by the module. Keep range-variable shadowing when
needed before Go 1.22, and use `sync.WaitGroup.Go` only with Go 1.25 or later. Use
`t.Context()` for test contexts when the project's Go version provides it.

Use the shared Go caches. Keep `GOMODCACHE` at `~/.local/pkg/mod` and `GOCACHE`
at `~/.cache/go-build` unless the project requires otherwise.

Run Go tests with `go test -timeout 60s`. Allow loopback sockets when tests use
local network listeners.

Place each lock field first in the paragraph of fields it guards. Put the lock
first, then the guarded fields, then a blank line.

### Tests

Use Testify only when the project already depends on it. When available, use
`assert.*` when a test can continue and `require.*` when it must stop; do not use
manual `if` blocks with `t.Error` or `t.Fatal`, or `if !assert.* { return }` guards.

Do not call `require.*` from `httptest` or `http.HandlerFunc` callbacks. Use
`assert.*` there and verify critical outcomes in the parent test because
`require.*` calls `FailNow`, which exits only the callback goroutine and can let
the parent test continue with invalid state.

Use `assert.Empty` or `require.Empty` only when nil and empty are equivalent.
Assert the exact value when the distinction is observable.

Group scenarios for one target under one top-level `TestTarget` function. Give
`t.Run` subtests plain-English scenario names that do not repeat the target; use
tables only for pure data or boundary cases differing solely in input and expected
output.

Use `require.EventuallyWithT` for bounded polling when Testify is available.
Prefer event-driven synchronization when the code exposes a suitable signal.

## Python

### Environment and Code

Use the Python version declared by the project. Otherwise use Python 3.12 or
later.

Use the project's existing environment and dependency workflow. Follow its
existing version-constraint and lockfile policy.

Add type hints to function signatures and complex variables. Prefer f-strings
for formatting and `pathlib.Path` for filesystem paths.

Distinguish expected absence from exceptional failure. Return `None` with an
optional type for expected absence, raise specific exceptions, manage resources
with context managers or explicit cleanup, and never use bare `except` clauses.

### Tests and Tooling

Use pytest only when the project configures or already uses it. In pytest
projects, use fixtures, plain `assert` expressions, and `pytest.raises`; do not use
`unittest`-style assertion methods.

Run the project's configured lint, format, type-check, and test commands before
committing. In uv projects configured for Ruff and ty, run:

- `uv run ruff check --fix`
- `uv run ruff format`
- `uv run ty check`

Do not add these tools when the project does not configure them.

## Git

Do not commit, create branches, stage unrelated changes, push, publish, deploy,
release, or open a pull request unless requested. Leave unrelated modifications
and external state untouched.

Use conventional commits in imperative mood with British English spelling.
Keep the subject under 50 characters; separate an optional body with a blank line
and wrap it at 72 columns. Describe the change without "currently," "now,"
"previously," dates, or PR and state snapshots.

Do not add attribution trailers. Never add `Co-Authored-By` or AI-generation
attribution such as "Generated with Claude" or "Generated with Bob."

## Writing

Use American English spelling in comments and documentation. Commit messages
remain an intentional exception and use British English.

Write new inline comments as terse engineer commentary. Use lowercase without
terminal punctuation for fragments and explain why rather than restating clear
code. Follow language conventions for API documentation and describe its public
contract even when that requires capitalization or complete sentences.

Classify every new or modified non-API comment as either a transient
implementation note or an enduring constraint. Do not commit point-in-time
narration, review commentary, change history, or explanations of the editing
process. Keep comments only for enduring constraints, non-obvious invariants,
external contracts, or consequences not clear from the code; state the
constraint directly and explain why it must hold.

Test each comment by reading it as someone opening the file who does not know
a change was made. Rewrite it when it only makes sense beside a diff, whether
framed as the decision taken ("we hold this back," "note that this is
buffered first") or as a contrast with the code it replaced ("instead," "no
longer," "rather than," "now," "the X that follows"). An imperative opening
is not narration and is often the clearest form: "buffer the diff so the
title can name the change."

Preserve comments during unrelated edits. Update them when the behavior or
contract changes, and carry them over verbatim when moving unchanged code.

Avoid narrated or promotional prose in comments and assertions. Avoid
"stampede," "starves," "stomp on," "drives," "surface," "leverage,"
"orchestrates," "robust," "seamless," "comprehensive," and long causal chains.
Prefer "do X (otherwise Y)" when explaining consequences.

Write the way the file already reads. Borrow the vocabulary of the codebase
and its domain rather than coining an abstraction for the comment ("the
verdict," "the deployed state," "the operation"), name the concrete
consequence rather than a rule about it ("it can block for --timeout," not
"it must not block"), and keep to plain verbs over "tolerate," "carry,"
"hand back," "decide," and "ensure."

Let a comment be lopsided. Explain the half a reader would not guess and
leave the rest unsaid: cover the case that bites rather than every case, drop
parentheticals that restate the sentence, resist balancing one clause against
another for symmetry, and do not repeat inline what the doc comment above
already says.

Use ASCII punctuation for prose conventions. Replace em dashes with commas or
semicolons, and arrow characters with `->`.

Reference issues as `#NNN`. Do not use `(see issue #NNN)` or
`as per issue NNN`.

## Excalidraw MCP

Set explicit `width` and `height` on every Excalidraw text element. Implicit
dimensions can render inconsistently across clients.