# 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.

## Production Safety

- 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.

## Configuration And Access

- 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.

## Testing Gates

- 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.

## Routing And Plugins

- 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.

## Telemetry

- 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.