# AGENTS.md

## Purpose

This repository uses AI coding agents for full-project Go code review and implementation work.

When asked to review code, inspect the entire repository and use repository-wide context. Do not limit analysis to the latest commit, pull request diff, or recently changed files unless the prompt explicitly narrows the scope.

## Operating modes

Treat review and implementation as separate modes:

- A request to review, audit, explain, or diagnose authorizes read-only inspection and non-mutating checks. Report findings, but do not edit files.
- A request to fix, change, implement, or build authorizes focused edits and the tests needed to verify them.
- A request to review and fix authorizes both activities.
- Do not turn review-only feedback into edits without explicit user authorization.

## Review priorities

Review the codebase with focus on:

1. correctness and reliability;
2. security and privacy;
3. concurrency, cancellation, and resource safety;
4. public API compatibility;
5. maintainability and architecture;
6. idiomatic Go;
7. testability;
8. performance when supported by code evidence or measurements;
9. documentation quality.

## Scope rules

- Review the whole repository unless the prompt explicitly narrows scope.
- Check cross-package interactions, public APIs, package boundaries, and shared patterns.
- Prefer concrete, actionable recommendations over generic advice.
- During implementation, make minimal, high-confidence changes within the requested scope.
- Preserve unrelated user changes and do not rewrite pre-existing work merely to make it consistent with the current task.
- When uncertain, state the confidence level, evidence, and assumptions.

## Project-specific constraints

- The project uses Go with CGO and a C++17 PoW implementation.
- Building and testing the PoW package requires a C++17 compiler and an x86-64 CPU with AVX2 support.
- Do not make live requests to the DeepSeek service during tests or routine verification.
- Never use real credentials, access tokens, device identifiers, or cookies in tests, examples, logs, or fixtures. PoW test vectors must be synthetic or explicitly public and non-sensitive.
- Use `httptest.Server` or a custom `http.RoundTripper` for HTTP tests.
- Do not log authorization headers or raw request and response bodies. If diagnostic body logging is ever explicitly required, redact secrets before the data reaches the logger.
- Keep network-dependent or hardware-specific integration tests separate from the default unit-test suite and document how to opt in.

## Go review expectations

Check for:

- bugs, fragile logic, invalid assumptions, nil handling issues, and resource leaks;
- weak error handling or errors that lose useful context;
- misuse of context, cancellation, timeouts, retries, and cleanup;
- race risks, deadlocks, blocking hazards, and unsafe shared state;
- non-idiomatic naming, APIs, interfaces, package structure, and error patterns;
- unnecessary complexity, duplication, or weak abstractions;
- performance problems supported by the code or benchmarks;
- unsafe input handling, secret leakage, insecure logging, injection risks, and risky file or network operations;
- portability problems introduced by CGO, compiler flags, CPU features, or platform assumptions.

## Documentation rules

Review comments where they affect the public API or explain non-obvious behavior.

### Exported declarations

Exported packages, types, funcs, methods, vars, and consts should have useful doc comments. A declaration may be documented by an appropriate group comment when that is clearer than repeating a comment for every member.

Each exported doc comment should:

- start with the identifier name when documenting a single declaration;
- explain purpose, behavior, constraints, or side effects;
- be concise without omitting important meaning;
- avoid mechanically repeating the signature;
- mention errors, ownership, concurrency, or lifecycle requirements when they are part of the contract.

### Unexported declarations

Do not require doc comments for every unexported declaration. Preserve comments that explain algorithms, protocol details, invariants, unsafe operations, performance decisions, or non-obvious constraints.

Report or rewrite comments only when they are missing from an important public contract, inaccurate, stale, misleading, redundant, or materially harder to understand than the code requires.

## Testing expectations

Treat tests as a required part of implementation and as an explicit review topic.

- Assess test quality, not only test presence.
- Add focused tests for changed behavior and regression tests for bugs being fixed.
- During review-only work, propose the smallest useful set of missing tests; do not add them.
- Prioritize public APIs, critical flows, negative paths, boundary conditions, cancellation, cleanup, and concurrency-sensitive logic.
- Prefer table-driven tests when they improve clarity; do not force them for one-off cases.
- If a case is hard to test directly, explain the gap and the most practical test strategy.
- Avoid tests that depend on timing, external services, real secrets, or unspecified machine state.

## Verification commands

For Go changes, run the relevant commands before finalizing:

```text
go test ./...
go vet ./...
go build ./...
```

Run `go test -race ./...` when the change affects concurrency and the current CGO/platform environment supports the race detector. Use repository-documented lint or formatting commands when present. If a command cannot run because the compiler, AVX2, CGO, network, or sandbox environment is unavailable, report the limitation instead of presenting the check as successful.

## Versioning and changelog

- Update `CHANGELOG.md` for user-visible behavior changes, public API changes, bug fixes, security fixes, and significant performance changes.
- Do not add changelog entries for tests, internal refactoring, formatting, routine comment cleanup, or `AGENTS.md`-only changes unless they change user-visible behavior.
- Add entries to an existing unreleased or next-version section. If no suitable section exists and choosing a version would require a product decision, ask the user rather than guessing.
- When Git history and release tags are available, verify changelog claims against the diff from the latest relevant release tag.
- Describe only changes that actually exist in the worktree. Do not rewrite or remove unrelated pre-existing changelog entries without user authorization.
- If the repository later adds a canonical version file, ensure its version agrees with the changelog section being edited.
- If `TODO.md` exists and the requested work completes one of its items, update that item using the file's existing format. Do not invent backlog files or modify an external wiki unless the user explicitly requests and authorizes it.
- `AGENTS.md`-only edits must never be added to `CHANGELOG.md`.

## Breaking changes policy

Treat the following as public API unless the repository explicitly documents otherwise:

- exported Go identifiers and their signatures;
- documented behavior, error semantics, ownership, and concurrency guarantees;
- request and response wire formats;
- configuration formats and supported command-line behavior.

- Detect potential breaking changes before editing a public API.
- Breaking changes require explicit user approval and a release version that permits them under the repository's versioning policy.
- For stable `v1+` releases, breaking changes require a new major version.
- If the current target version does not permit the change, stop and offer: keep existing behavior, introduce a small backward-compatible alternative, or select an appropriate release version.
- Prefer additive compatibility when it remains small, clear, and maintainable; do not accumulate compatibility layers that obscure the API.

## Commit message format

When the user asks for a commit message, output only a directly copyable plain multiline block:

- Use one to four short lines.
- Format every line as `(<kind>): <text>`.
- Use a concise kind such as `new`, `fix`, `refactor`, `ci/cd`, `tests`, or `doc`.
- Keep `<text>` concise and high-signal; do not turn it into a changelog.
- When multiple lines are needed, order kinds as: `new`, `fix`, `refactor`, `ci/cd`, `tests`, `doc`.

## Commit signing

- Create commits only when the user explicitly requests one.
- All commits created by an agent must be GPG-signed.
- If signing or pushing requires leaving the sandbox, request escalation before running the command.
- If a signed commit cannot be created successfully, report the failure and stop instead of creating an unsigned fallback.

## Review severity

- **Critical:** likely credential compromise, data loss, remote code execution, or broad production outage requiring immediate action.
- **Major:** a reproducible correctness, security, compatibility, resource, or concurrency defect that can affect normal use.
- **Minor:** a localized robustness, maintainability, documentation, or testability issue with limited immediate impact.
- Do not inflate severity for style preferences. If impact depends on an unverified assumption, state that explicitly.

## Review output

For repo-wide reviews:

- Lead with findings, ordered by severity and then by impact.
- For each finding include location, issue, impact, evidence, and recommended fix.
- Separate confirmed defects from suggestions and open questions.
- Include test gaps, documentation issues, and good decisions only when there is useful content to report.
- Omit empty sections. If there are no findings, say so explicitly and list the checks performed and any verification limitations.
- Include a summary of concrete changes only when implementation was authorized and changes were actually made.

## Working style

- Be direct, specific, and action-oriented.
- Do not stop at style-only feedback.
- Use full repository context before drawing conclusions.
- Prefer minimal, high-confidence patches.
- Preserve behavior unless intentionally fixing a confirmed bug or implementing an approved behavior change.