From 60989cd72f101978d3eebf35e8915196be5f8e60 Mon Sep 17 00:00:00 2001
From: pragent AI review bot <pragent-bot@local.domain>
Date: Thu, 20 Aug 2026 18:49:06 +0000
Subject: [PATCH] docs: add CONTRIBUTING.md (testing requirements + pragent
 notes)

Specifies what counts as "tested" for this repo, the local test
commands the bot treats as gates, and how pragent reads the repo
config (`.pr-review.json` + static architecture.md from Nexus
raw-hosted).
---
 CONTRIBUTING.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..782c09d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,93 @@
+# Contributing — Canalhandia (Canalhandia Minecraft plugin)
+
+Canalhandia is a Minecraft Paper plugin that adds PT-BR chat games, item
+protection, and other in-game commands for the Canalhandia server. This repo
+holds the plugin source. The companion server config lives at
+`gitea_admin/canalhandia-config`.
+
+## Before you open a PR
+
+1. **Fill in the PR template** (`.gitea/pull_request_template.md`). The
+   *Risk* checklist is the part pragent scores you on — check the boxes that
+   apply, delete the ones that don't.
+2. **Update the static context** if your change introduces new house rules.
+   See `## Adding house rules` below.
+3. **Run the gates locally** (see *Test commands*). CI is a single
+   `mvn -B test` against JDK 25 — there's no other infra in this repo.
+
+## Test commands
+
+```bash
+# Run the test suite (JDK 25 required). Same command CI uses:
+mvn -B test
+
+# Compile only (faster):
+mvn -B -DskipTests package
+
+# Integration: copy the resulting jar into a test Paper server's plugins/
+# directory, start the server, exercise the affected commands. The chat
+# and stats paths are NOT covered by unit tests — they need a live server.
+```
+
+### What counts as "tested"
+
+For pragent (and reviewers) to consider a change tested, the PR must show:
+
+- [ ] `mvn -B test` output from your machine pasted in the PR, **OR** a CI
+      run URL.
+- [ ] A new behaviour has a JUnit test in `src/test/java/...` that exercises
+      the new code path. New `comando:` blocks need at least one test that
+      sends a fake event and asserts the message format.
+- [ ] If the change touches the chat immutability rule, the singular-form
+      rule, or the Bedrock fallback, a manual test on a Paper server is
+      required **and** a one-line note pasted in the PR.
+- [ ] If the change touches `<world>/players/stats`, you must show the
+      file path on a running server (`ls <world>/players/stats/*.json`)
+      and confirm the stats file is updated, not the wrong path.
+
+### Out of scope for tests
+
+- Performance / load tests (none in this repo).
+- E2E against the live server (manual; verify in `canalhandia-config` repo).
+- UI / browser tests (no web surface).
+
+## Commit messages
+
+Conventional commits. Examples:
+
+- `feat: add per-player cobblestone counter command`
+- `fix(void): keep inventory when dying in lava void`
+- `docs: update README build instructions`
+- `chore: bump pom parent to 1.4.2`
+
+## Branch names
+
+`<type>/<short-kebab-description>` matching commit type. Example:
+`fix/void-keep-inventory`.
+
+## PR review
+
+- The bot (`pragent`) reviews every PR labelled `AI-REVIEW`. It reads
+  `.pr-review.json` from `main` + the static `architecture.md` from Nexus
+  raw-hosted. Adding a new house rule? Update both.
+- Add the `AI-USAGE` label if you want the bot to also post a token /
+  cost-equivalent report on the review.
+
+## Adding house rules
+
+If your PR changes how translatable components behave, how chat edits work,
+how stats are read, or how the Bedrock fallback is rendered, you must:
+
+1. Update the relevant section in the static `architecture.md` (upload a new
+   copy to Nexus raw-hosted at `canalhandia/architecture.md`).
+2. Bump `.pr-review.json:instructions` with a one-paragraph summary.
+3. Add a finding-checklist item to `.gitea/pull_request_template.md` *Risk*
+   section so PR authors know to confirm the rule.
+
+Bot does not detect house-rule drift automatically — these three updates
+together are the maintainer contract.
+
+## Rollback
+
+A single PR that bumps the plugin jar in `canalhandia-config` rolls back.
+Plugins are jar-swapped, no migrations.
\ No newline at end of file