JWeBot Agent Rules

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

Versioning

Use alpha X.Y.Z.MMDD.
Small changes increment only Z.
Do not move to a new minor 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.

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.