82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
## Mandatory Release Settlement
|
|
|
|
- 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.
|
|
|
|
## 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.
|