# AGENTS.md

## Commands
- Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below.
- Generate: No code generation is configured; format with `gofmt -w .`.
- Documentation: `go run ./cmd/docs check`; create records with `go run ./cmd/docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.

## Scope and decisions
- Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it.
- Explicit user instructions win; nearer scoped rules override broader rules.
- Distinguish confirmed requirements, proposed defaults and unresolved decisions; resolve material ambiguity before dependent work.
- Proposed ADRs are context, not authority; read relevant accepted decisions before changing their scope.
- Before final review and merge, reconcile affected records against the latest target branch plus the PR, following [/docs/adr/README.md](/docs/adr/README.md).
- Documentation tier: ADRs only. Create a plan only when work needs durable execution context across areas, phases or sessions; then enable the plans tier.
- In a sandbox, request required network/cache access before first codegen; on permission/cache errors retry once with that access. Never hand-edit generated output.
- Shared databases and ports may belong to other worktrees/agents; read project rules before starting, stopping or resetting them.
- Ask before lint/autofix changes that could alter runtime behavior.
- Report commands actually run and their results; never claim an unrun check passed.
- Name branches `<type>/<kebab>` without agent-name prefixes.

## Comments
- Document package/module purpose, ownership and boundaries, and every public/exported contract in native doc comments; document generated surfaces at their source.
- Explain why at invariants, auth decisions, concurrency/ordering, destructive edges and deliberate deviations; no narration, changelog comments or commented-out code.
- Use `invariant: <property>`, `authz: <who and enforcement>`, `shortcut: <limit>, <when to upgrade>` on relevant code; retain Go `Deprecated:` and Rust `// SAFETY:`.
- Every TODO needs an issue URL; reviewers recheck tagged comments on touched code.

## Project map

Go module `go.auvem.com/corestack`.

- Docs format (the spec `docs check` implements): `docs/docs-format.md`.
- Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them.
- Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [proposed module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)).

## Go
- Default backend language is Go; follow existing package boundaries.
- Define interfaces at the consumer only when a second implementation or a test seam needs one.
- Wrap contextual errors with `%w`; inspect causes with `errors.Is`/`errors.As`.
- Do not add package-level mutable state or `init` side effects.
- Put `context.Context` first in parameters; never store it in a struct.
- Give every goroutine an owner and a shutdown path.
- Run `gofmt`, `go vet ./...`, tests and the project's configured linter from the owning module.
- Use `.golangci.yml` (revive exported/package-comments); the pinned linter command is listed above.

## TODO check

Run from the project root (also enforced in CI):

```sh
find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
```