JWeBot Agent Rules

These rules are mandatory for every automated change in this repository.

Versioning

Use beta X.Y.Z.MMDD for current beta releases.
Python package versions use PEP 440 pre-release form, for example X.Y.Zb1+MMDD.
Small changes increment only Z.
Do not move to a new minor or stable version without explicit user approval.
Keep VERSION, root pyproject.toml, package versions, package __version__, README.md, and CHANGELOG.md synchronized.

Do not deploy until local and staging gates pass.
Before production cutover, verify a restorable baseline or use the coordinated production deployer.
Keep only jwebot-edge.service and wechat-ocr-adaptive-recorder.service active for OCR/Edge. Legacy OCR services remain installed but disabled unless explicitly used for recovery.
Never bypass the ready-window, empty-queue, Edge health, SQLite integrity, or adaptive restart-stability gates.
If a deployment gate fails, verify rollback state before retrying.

Every successful production update must run jwebot_release_update.py after cutover gates pass and before the release is declared complete.
Each release grants exactly 200 Mora to every account that exists when the settlement starts. The grant and account movement are idempotent by version.
The first bullet in each release's CHANGELOG.md section must be one concise, user-facing sentence suitable for the group update announcement.
After crediting accounts, send the version, first changelog bullet, and Mora x200 compensation notice through the guarded group sender.
Never blindly retry an uncertain announcement. Verify the group visually, then use --retry-uncertain-announcement only when the prior message did not land.
A production release is incomplete until compensation, announcement, SQLite integrity, empty queues, Edge health, and service stability pass.

Real profiles live under ~/.config/jwebot/, never in the repository.
Debug, incident, telemetry, and root-operation state belongs under ~/.local/state/jwebot/.
Use an operator-provided SSH host alias and elevate locally. Do not enable direct root SSH or weaken key restrictions.
Never write secrets, passwords, API keys, private keys, person context, SteamIDs, host addresses, or message payloads into Git, docs, logs, or memory.

Run PATH="$PWD/.venv/bin:$PATH" ./tools/check-local.sh before committing release changes.
Staging must use the same configured runtime Python as production.
Any GUI sender change must test primary send, fallback, and visual confirmation handling.
Any plugin command change must pass tools/sync-local-extensions.py --check and package validation.
Open-source release changes must pass tools/check-secrets.py --history after history cleanup.

Registered slash commands must be explicit in the ownership inventory.
New local commands should be reviewed plugin descriptors and generated adapters unless they are truly Kernel-only.
Runtime command ownership freezes at startup.
Plugin code may return structured intents only. It must not access GUI, raw SQLite/Ledger, shell, SSH, Docker, environment secrets, filesystem, or unrestricted network.

Keep telemetry privacy-safe: no message body, sender name, raw group ID, reply text, secret, environment value, or provider payload.
Use hashed event/group IDs and bounded error class names only.
Preserve per-step telemetry before latency optimization. Production performance claims require p50/p95 evidence and duplicate/order checks.