gasm-sdk/AGENTS.md

# AGENTS.md — gasm-devkit

Repository rules for AI agents and contributors. Read before modifying any
code in this repository.

## AI Contribution Policy

AI agents may assist with code, documentation, tests, and review in this
repository. All AI-assisted changes must:

- Follow the code style and conventions in this file.
- Include the trailer `Assisted-by: <model-name>` in every commit message.
- Not commit directly to `main` — work on `development`.
- Pass the full Definition of Done before any commit.

## Workflow

- **Branching.** `development` is the working branch. `main` is
  release-only: merge from `development`, then tag. Never commit directly
  to `main`.
- **Release procedure.**
  1. Bump `version` in `justfile` and `cmd/gasm/main.go`.
  2. Update `CHANGELOG.md` with a new `## [X.Y.Z] — YYYY-MM-DD` section.
  3. Update `README.md` and `docs/ARCHITECTURE.md` if user-visible
     behaviour changed.
  4. Run the Definition of Done (below).
  5. Commit on `development`.
  6. `git checkout main && git merge --ff-only development`.
  7. `git tag vX.Y.Z`.
  8. `git checkout development`.
  9. `GOBIN=~/.local/bin just install-bin`.

## Commit Messages

Conventional Commits, subject line only, imperative mood, lowercase after
the colon:

```
feat(asm): add EVEX gather and scatter with VSIB addressing
```

Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
`chore`, `ci`, `build`, `revert`.

Every commit ends with exactly one trailer, using the model that
assisted with the change:

```
Assisted-by: <model-name>
```

Replace `<model-name>` with the actual model (e.g. `DeepSeek V4 Pro`).

No body, no footers, no trailing period on the subject.

## Code Style

Language: Go 1.27 (`toolchain go1.27rc1`).

### Formatter

`gofmt` — zero diff. Run `just fmt` before committing.

### Linter

`go vet` — zero warnings. Run `just build` before committing.

### Tests

`go test -race -count=1 ./...` — all green, coverage ≥ 80 % (hard gate,
enforced by `just test`).

### Dependencies

- **Production code:** standard library only. No third-party imports in
  shipped code.
- **Test code:** `golang.org/x/arch` is the sole test dependency (decode
  oracle for round-trip validation). It is never linked into the binary.
- **No cgo, no C, no external toolchains, no JavaScript.**

### Error Handling

Explicit `if err != nil`. Wrap with `fmt.Errorf("context: %w", err)`.
No panics outside `main`. The one exception: the JIT trampoline's
`recover`-guarded decoder hot path, which converts bounds panics to
sentinel errors.

### Assembly

Plan 9 syntax (Go's assembler dialect). Hand-written — no code generators
except `_gen/gen.go` for instruction tables (which parses the Go
toolchain source). Every instruction table is committed; no runtime
dependency on the Go toolchain.

### File Naming

- `_amd64.s`, `_arm64.s`, `_riscv64.s`, `_loong64.s` for
  architecture-specific assembly.
- `_linux_amd64.go` for platform-specific Go files.
- `_test.go` suffix for test files.

## Definition of Done

A task is not complete until all of these pass:

1. `just build` — `go vet` + `gofmt` check, zero errors, zero warnings.
2. `just test` — full suite with `-race`, coverage ≥ 80 %.
3. `just fmt` — produces no diff.
4. Diagnostics — zero warnings across the project.
5. Non-trivial changes reviewed.

## Licence

BSD-3-Clause. Every source file carries the SPDX header:

```
// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
// SPDX-License-Identifier: BSD-3-Clause
```