Define the required code and commit rules

The skills set declaration order, owning test filenames, multiline
separators, and explicit handling of ignored errors. Review covers the
rules that the current checks do not enforce, so a tool pass does not
stand for full style compliance.

Every commit uses the configured signing key and needs cryptographic
verification. Code and issue pushes need permission, as does a rewrite
of published history, so routine steps do not imply that consent.

Issue: 3cdc678

diff --git a/.agents/skills/check/SKILL.md b/.agents/skills/check/SKILL.md
index e920bc388c1a61617477102bf0d306d9cf551484..688226773f5c4f65018ccc75b1218d8dcdea361a 100644 (file)
--- a/.agents/skills/check/SKILL.md
+++ b/.agents/skills/check/SKILL.md
@@ -13,19 +13,27 @@ Run every command in the Nix development shell. Use
 1. Format all files with `bin/format`.
 2. Run the checks with `bin/check`. Its golangci-lint config keeps the
    standard linters and adds `errorlint`, `gocritic`, `testifylint`,
 1. Format all files with `bin/format`.
 2. Run the checks with `bin/check`. Its golangci-lint config keeps the
    standard linters and adds `errorlint`, `gocritic`, `testifylint`,

-   `revive`, `wrapcheck`, `nlreturn`, and `wsl_v5`. The settings in
-   `.golangci.yml` match the Go rules.
+   `revive`, `wrapcheck`, `nlreturn`, and `wsl_v5`. These checks cover
+   only part of the Go rules. A pass is not proof of compliance.

 3. Run `git add` on new files, then run `nix build` and
    `nix flake check`.
 4. Fix every failure and run the steps again. Do not disable a linter or
 3. Run `git add` on new files, then run `nix build` and
    `nix flake check`.
 4. Fix every failure and run the steps again. Do not disable a linter or

-   add a `nolint` directive to get a pass, unless the user agrees.
+   add a `nolint` directive to get a pass. An intentional error discard
+   needs the user's approval, an explicit directive, and a comment that
+   gives the reason, as the `go-code` skill requires. Never replace a
+   checked error with a blank assignment to get a pass.

 5. Review the final diff against the rules. Passing tools do not replace
    this review.
    - Read `AGENTS.md` and the `SKILL.md` of each skill of the task again
      from disk now. Do not work from memory of an earlier read.
    - Go through the diff one rule at a time, and for each rule look at
      every changed line that it covers. For Go code, check each section
 5. Review the final diff against the rules. Passing tools do not replace
    this review.
    - Read `AGENTS.md` and the `SKILL.md` of each skill of the task again
      from disk now. Do not work from memory of an earlier read.
    - Go through the diff one rule at a time, and for each rule look at
      every changed line that it covers. For Go code, check each section

-     of `go-code`, also for the tests.
+     of `go-code`, also for the tests. Check declaration order, owning
+     test filenames, separators after multiline constructs, and errors
+     assigned to `_`. Inspect blank-assigned errors even when `errcheck`
+     reports none: `.golangci.yml` does not enable its `check-blank`
+     setting. Check whole comment paragraphs against the `docs` skill,
+     not only their line width.

    - Fix each finding, then run steps 1 to 4 again.
 
 Tell the user about each check that cannot run and each failure that
    - Fix each finding, then run steps 1 to 4 again.
 
 Tell the user about each check that cannot run and each failure that

diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md
index 7e1f65766ba55b8bc9c37816c7ee4f565d679dc8..14ea4b3d26d11fa47e6d300f41db737fd5dde9c8 100644 (file)
--- a/.agents/skills/commit/SKILL.md
+++ b/.agents/skills/commit/SKILL.md
@@ -7,20 +7,33 @@ description: Commit procedure and message rules. Use for every commit.
 
 ## Procedure
 
 
 ## Procedure
 

-1. Do the `check` skill. All checks must pass before you commit.
-2. Stage only the files that belong to this change. Keep unrelated
+1. Confirm that the configured signing key is available. If signing is
+   unavailable or fails, stop and report the problem. Never disable
+   signing, bypass it with a command or configuration override, or
+   create an unsigned commit.
+2. Do the `check` skill. All checks must pass before you commit.
+3. Stage only the files that belong to this change. Keep unrelated

    changes in separate commits.
    changes in separate commits.

-3. Write the message to a file or a here-document and commit with
-   `git commit -F`. Never put `\n` in `git commit -m`.
-4. When `.githooks/commit-msg` rejects the message, fix the message and
+4. Write the message to a file or a here-document and sign the commit
+   with the configured key, using `git commit -S -F`. Never put `\n` in
+   `git commit -m`.
+5. When `.githooks/commit-msg` rejects the message, fix the message and

    commit again. Do not skip the hook with `--no-verify`.
    commit again. Do not skip the hook with `--no-verify`.

+6. Cryptographically verify each new commit's signature against the
+   configured key before reporting completion. A signature header alone
+   is not verification. If verification fails, stop and report it. Do
+   not claim completion or publish the commit.

 
 ## Size
 
 - Commit often. Split the work into small, coherent, working steps, and
   do not wait for a full feature.
 
 ## Size
 
 - Commit often. Split the work into small, coherent, working steps, and
   do not wait for a full feature.

-- Before a push, rebase on the latest `master` and fix conflicts during
-  the rebase. Never make a merge commit.
+- Push code only with the user's authorization. A remote does not give
+  permission to push.
+- Rebase before an authorized push only when the task permits it. Do not
+  rewrite published commits without the user's explicit approval. Stop
+  and ask when an operation needs that approval. Never make a merge
+  commit.

 
 ## Subject
 
 
 ## Subject
 


@@ -45,9 +58,10 @@ description: Commit procedure and message rules. Use for every commit.
 ## Trailers
 
 - When the change belongs to an issue, end the message with one `Issue:`
 ## Trailers
 
 - When the change belongs to an issue, end the message with one `Issue:`

-  trailer with the git-bug ID of that issue. Add it with
-  `git commit --trailer`. Never use a closing keyword such as "Fixes" or
-  "Closes".
+  trailer. Use the shortest unique git-bug issue ID in the `Issue:`
+  trailer, with a minimum of seven characters. Check uniqueness against
+  all issues, not only open issues. Add it with `git commit --trailer`.
+  Never use a closing keyword such as "Fixes" or "Closes".

 - Link the bug report when a change fixes a reported bug.
 - Do not add an AI tool as co-author. Do not add attribution trailers.
 
 - Link the bug report when a change fixes a reported bug.
 - Do not add an AI tool as co-author. Do not add attribution trailers.
 

diff --git a/.agents/skills/go-code/SKILL.md b/.agents/skills/go-code/SKILL.md
index 213a7d5aacfa004851b75794f38876f5c890b0b2..374c2e932d810090dc29af95043f7b20f0490e12 100644 (file)
--- a/.agents/skills/go-code/SKILL.md
+++ b/.agents/skills/go-code/SKILL.md
@@ -24,10 +24,15 @@ description: Go style rules. Use before you write or review Go code.
   case.
 - Write all the letters of an initialism in one case. `revive` checks
   common initialisms.
   case.
 - Write all the letters of an initialism in one case. `revive` checks
   common initialisms.

-- Put entry points first, then each struct's methods as a group, then
-  standalone utility functions. Do not put a utility function between
-  the methods of one type.
-- In each group, order functions by first use in the file.
+- Order declarations as imports, constants, variables, types,
+  constructors, methods, then standalone helpers. Types include structs,
+  interfaces, and aliases. Put all types before any constructor or
+  method, also when a file holds more than one type. The Tests section
+  gives the exception for files with tests.
+- Keep each type's methods in one group. Do not put a helper between
+  them. Order functions by first use within their declaration group, not
+  across groups. Entry points do not go before types or constructors
+  merely because they are entry points.

 
 ## Entry point and context
 
 
 ## Entry point and context
 


@@ -52,7 +57,12 @@ description: Go style rules. Use before you write or review Go code.
 
 ## Errors
 
 
 ## Errors
 

-- Handle every returned error.
+- Handle every returned error, including an error assigned to `_`. Never
+  use a blank assignment to hide an unchecked error from a linter.
+  Handle meaningful errors. When the user approves an intentional
+  discard, call the operation with an explicit `// nolint: errcheck`
+  directive and a comment that gives the reason, not a blank assignment.
+  The `check` skill gives the approval rule.

 - Reuse an existing `err` for later operations in the same scope. Use a
   different variable only to keep or join errors.
 - Use `errors.Is` and `errors.As` to examine errors. Do not compare an
 - Reuse an existing `err` for later operations in the same scope. Use a
   different variable only to keep or join errors.
 - Use `errors.Is` and `errors.As` to examine errors. Do not compare an


@@ -94,11 +104,14 @@ description: Go style rules. Use before you write or review Go code.
   table-driven test. A small type of two fields that acts as one value,
   such as a key or a coordinate pair, can use a positional literal on
   one line.
   table-driven test. A small type of two fields that acts as one value,
   such as a key or a coordinate pair, can use a positional literal on
   one line.

-- Put an empty line between logical blocks, also after multiline
-  declarations, assignments, literals, and calls. Keep an operation with
-  its immediate error or result check. Keep a short declaration with its
-  immediate use. `wsl_v5` and `nlreturn` check part of this rule. Review
-  the remaining logical blocks and immediate-use groups by hand.
+- Put an empty line between logical blocks and after multiline
+  declarations, assignments, literals, and calls. The only exception
+  after a multiline construct is its immediate error check. Separate a
+  multiline literal from a following loop, even when the loop uses that
+  literal. Keep a single-line declaration with its immediate use, and an
+  operation with its immediate error check. This does not waive the
+  separator after a multiline construct. `wsl_v5` and `nlreturn` check
+  only part of this rule. Review the other boundaries by hand.

 - Use GNU-style command flags: two dashes for long flags, such as
   `--cwd`, and one dash only for one-letter flags, such as `-h`.
 - Prefer the Go standard library. Prefer Go over cgo.
 - Use GNU-style command flags: two dashes for long flags, such as
   `--cwd`, and one dash only for one-letter flags, such as `-h`.
 - Prefer the Go standard library. Prefer Go over cgo.


@@ -121,8 +134,19 @@ description: Go style rules. Use before you write or review Go code.
 - Name a table-driven case slice `testCases` and its range variable
   `tc`. A subtest name describes the behavior, not a generic outcome or
   input.
 - Name a table-driven case slice `testCases` and its range variable
   `tc`. A subtest name describes the behavior, not a generic outcome or
   input.

-- In a test file, put constants immediately after the imports, then the
-  tests, then supporting types, methods, and helpers.
+- Each file with tests must have the name of its owning production file
+  with `_test` before `.go`: `memory_test.go` tests `memory.go`. Move
+  scenario and integration tests into their owner's test file. Do not
+  add an empty production file to make a test filename valid. Only
+  `_helper_test.go` files are exempt from this pairing rule.
+- In an ordinary `_test.go` file, order declarations as imports,
+  constants, variables, tests, supporting types, constructors, methods,
+  then helpers. This tests-first order is the exception to the
+  production order. Put all supporting types before their constructors
+  and methods.
+- A `_helper_test.go` file has no tests. Order its declarations as
+  imports, constants, variables, types, constructors, methods, then
+  helpers, as in a production file.

 - Keep a helper that only one test file uses in that file. Put a helper
   that more than one test file uses in a file without tests. Name that
   file for what it holds, and end the name with `_helper_test.go`.
 - Keep a helper that only one test file uses in that file. Put a helper
   that more than one test file uses in a file without tests. Name that
   file for what it holds, and end the name with `_helper_test.go`.

diff --git a/.agents/skills/issues/SKILL.md b/.agents/skills/issues/SKILL.md
index 104a04cccf78f431bb292d5bf83d80481439da61..6ed42de4220e5f731137e244a1cd1f2077155fca 100644 (file)
--- a/.agents/skills/issues/SKILL.md
+++ b/.agents/skills/issues/SKILL.md
@@ -60,7 +60,9 @@ that match any of the words, and it reads `Parent:` as a query
 qualifier. Nothing checks the trailers. Before you close a parent, make
 sure that its children are closed.
 
 qualifier. Nothing checks the trailers. Before you close a parent, make
 sure that its children are closed.
 

-Push the issues with `git bug push` when the repository has a remote.
+Push issues with `git bug push` only when the user authorizes it. A
+remote does not give permission to push. Do not rewrite published
+history without the user's explicit approval.

 
 This example creates an issue:
 
 
 This example creates an issue: