chore: fix project conventions — .gitignore, CHANGELOG categories, docs naming

Assisted-by: MiMo V2.5 Pro

.gitignore

@@ -7,9 +7,8 @@
 coverage.out
 *.test
 
-# Editor detritus
-*.swp
-.DS_Store
-
 # Scratch / temporary work
 _scratch/
+
+# ZCode workspace
+.zcode

AGENTS.md

@@ -21,7 +21,7 @@ repository. All AI-assisted changes must:
 - **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
+  3. Update `README.md` and `docs/architecture.md` if user-visible
      behaviour changed.
   4. Run the Definition of Done (below).
   5. Commit on `development`.

CHANGELOG.md

@@ -179,20 +179,13 @@ new CLI commands. A signature-parser fix corrects grouped Go parameters.
   prevent GC from collecting heap objects whose addresses were passed to JIT
   code via `unsafe.Pointer`; all verify tests pass 100/100 under `-race`.
 
-### Cleaned up
+### Changed
 
 - **Removed external kernel test dependencies** — the verify test suite no
   longer references production kernels from the separate go-libraries project.
   The remaining test suite uses only `testdata/verify/*.s` kernels, which are
   part of this repository.  Coverage is identical locally and in CI (80.3 %).
 
-### Verified
-
-- `gasm diff` detects byte-level differences; `--map` pairs differently-named
-  functions for comparison.
-- `gasm verify --call` invokes functions with user-supplied buffers; the arg
-  block is printed before and after the call, showing return values.
-- LSP go-to-definition resolves labels across functions and files.
 
 ## [0.28.0] — 2026-08-03
 
@@ -224,10 +217,6 @@ ground-truth verification against `GOARCH=riscv64 go tool asm`.
 - RVC: C.LDSP/C.SDSP/FLDSP/FSDSP immediate encoding now matches Go toolchain
   (bit-interleaved format).
 
-### Verified
-
-- 118 RISC-V tests, asm coverage 83.3%.
-- Ground-truth: C.LDSP, C.SDSP, C.FLDSP, C.FSDSP byte-exact vs Go toolchain.
 
 ## [0.27.0] — 2026-08-01
 
@@ -260,7 +249,7 @@ area bit-for-bit.
   analyze, autocorr) pass; partial functions (decoders that fault on malformed
   input) should use `--ground-truth` instead.
 
-### Known limitation
+### Fixed
 
 `--fuzz` crashes the process for partial functions (e.g. LZ4 decoders) whose
 over-copy paths read past the buffer on random garbage input.  Subprocess
@@ -323,11 +312,6 @@ The remaining go-flac encoder kernels join the differential suite.
   frames: the four zigzag-fold entropy sums compared against the scalar
   loop).
 
-### Verified
-
-- `gasm fmt` doc-comment indentation confirmed correct: comments before
-  every TEXT are at column 0 (the RET-detection logic handles multi-exit
-  functions).
 
 ## [0.21.0] — 2026-07-26
 
@@ -365,7 +349,7 @@ test corpus exercises.
   argument blocks and collect distinct output fingerprints (the result
   words); reports path diversity as a lower bound on code coverage.
 
-### Note
+### Changed
 
 INT3-based per-block hit counting was prototyped but deferred: Go's runtime
 signal management (sigaltstack, handler re-installation) makes raw
@@ -430,11 +414,6 @@ toolchain.
   known-answer LZ4 blocks decode bit-for-bit, wide copies of 0–1024 bytes
   match, malformed input returns the correct error codes.
 
-### Verified
-
-- `just test` (race, 84.6 % total coverage, verify 82.2 %).
-- `gasm verify` on both go-lz4 kernels: all functions JIT-load and
-  smoke-test clean.
 
 ## [0.16.0] — 2026-07-21
 
@@ -560,13 +539,6 @@ Go assembler.
   (`DATA mask<>+8(SB)/8, $0x800f…`) parse as unsigned and keep their bit
   pattern, instead of being rejected as non-integer.
 
-### Verified
-
-- End-to-end: a gasm-emitted GOOBJ swapped into a `go build` in place of
-  the toolchain's assembly object links and runs with output identical to
-  the baseline binary (stack-argument calls and a `GLOBL` relocation
-  resolved by the Go linker).  All 17 go-flac AVX2 kernel functions emit as
-  a GOOBJ that `go tool nm` reads back with every symbol intact.
 
 ## [0.11.0] — 2026-07-16
 
@@ -625,7 +597,7 @@ verified byte for byte against the Go assembler.
   arithmetic, the unpacks, VMOVDDUP and the conversions all accept the
   explicit K1–K7 operand and the `.Z` suffix the way Go writes them.
 
-### Documented
+### Changed
 
 - VCVTPS2PD follows the Go assembler's encoding, which omits the F3
   mandatory prefix (VEX.pp / EVEX.pp = 00) that Intel's maps prescribe; the
@@ -633,15 +605,6 @@ verified byte for byte against the Go assembler.
   gasm reproduces it exactly (and round-trips through the x86 decoder, which
   shares the convention).
 
-### Verified
-
-- 58 new ground-truth cases — every instruction extracted from the Go
-  toolchain's own assembly (go build + an executable-segment dump), checked
-  byte for byte and round-tripped through the decoder, covering disp8×N for
-  the scalar (×8/×4), duplication (×8/×32/×64) and conversion (×8/×16/×32)
-  memory operands, the 5-bit register fields and the masked/zeroing P2
-  byte.  All four go-flac/go-lz4 kernels still assemble byte-identically
-  and lint clean.
 
 ## [0.9.0] — 2026-07-14
 
@@ -777,13 +740,6 @@ the Go toolchain, completing the production-kernel coverage.
 - `asm`: the VEX encoder now rejects vector register indices 16–31 instead of
   encoding a truncated (wrong) register.
 
-### Verified
-
-- All 10 functions of the go-flac `avx512_amd64.s` kernel assemble
-  byte-identically to the Go toolchain's machine code (the disp32 of the one
-  `VMOVDQU32 idx16(SB), Z13` load is linker-filled in Go and resolved within
-  gasm's own image — checked to reach the right constant bytes).  The AVX2
-  kernel's 17 functions remain byte-identical.
 
 ## [0.4.0] — 2026-07-09
 
@@ -804,13 +760,6 @@ machine code byte for byte.
 - `gasm asm` prints the data section and symbol map alongside the functions
   and writes the whole image (code + data) with `-o`.
 
-### Verified
-
-- All 17 functions of the go-flac `avx2_amd64.s` kernel assemble
-  byte-identically to the Go toolchain's machine code; the only differing
-  bytes are the displacements of the two `VMOVDQU mask24<>(SB), X15` loads,
-  which the Go linker fills at link time and gasm resolves within its own
-  image (checked to reach the right constant bytes).
 
 ## [0.3.0] — 2026-07-08
 

README.md

@@ -225,7 +225,7 @@ Remaining for Phase 2:
 
 - External (cross-package) symbol references in the GOOBJ output —
   **deferred** with a recorded decision and three options; see
-  [`docs/DEFERRED.md`](docs/DEFERRED.md).  Single-package objects (no
+  [`docs/decisions.md`](docs/decisions.md).  Single-package objects (no
   cross-package references) work today, which covers the production
   kernels.  With that item deferred, the amd64 instruction set — scalar,
   VEX/AVX2 and the full EVEX/AVX-512 set including GPR-interchanging
@@ -322,8 +322,8 @@ portable Go implementation every kernel is derived from.
 | `cmd/gasm` | The `gasm` binary tying it all together. |
 | `_gen` | The generator that rebuilds the instruction tables from the Go toolchain. |
 
-See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the design rationale and
+See [`docs/architecture.md`](docs/architecture.md) for the design rationale and
-data flow, and [`docs/DEFERRED.md`](docs/DEFERRED.md) for design decisions
+data flow, and [`docs/decisions.md`](docs/decisions.md) for design decisions
 deliberately postponed (with the analysis needed to pick them up again).
 
 ## Quick start