docs: add the full documentation surface — AGENTS, CONTRIBUTING, cli and development references

Assisted-by: DeepSeek V4 Flash
2026-08-01 05:22:00 +02:00
parent 89d633f4bb
commit c77d68018c
7 changed files with 1519 additions and 0 deletions
@@ -0,0 +1,119 @@
+# 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.26 (`toolchain go1.26.5`).
+
+### 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
+```