JWeBot/docs/project-rules.md

Project Rules

These rules describe the mandatory workflow for JWeBot changes. They are not advice; future changes must either follow them or document an explicit user exception.

Release Discipline

• Version format is beta X.Y.Z.MMDD for current beta releases.
• Python package versions use the matching PEP 440 beta form, such as X.Y.Zb1+MMDD.
• Patch changes increment Z; minor, major, or stable-release changes require explicit user approval.
• A release change must update:
  • VERSION;
  • root pyproject.toml;
  • every package pyproject.toml;
  • every package __version__;
  • README.md;
  • CHANGELOG.md.
• The first bullet under each release heading in CHANGELOG.md must be one concise, user-facing sentence. It is the canonical group announcement summary.
• Do not mark production complete merely because code was committed. Production is complete only after staging, cutover, acceptance, observation, and backup restore checks pass.

Mandatory Pre-Production Gates

Before touching production runtime files on production host:

1. Local working tree must be understood and intentionally staged.

2. Local gate must pass:

   PATH="$PWD/.venv/bin:$PATH" ./tools/check-local.sh
   

3. Upload a clean staging snapshot using Git-tracked files only.

4. Verify staging file hashes against the local tree.

5. Run the complete production host gate with:

   PATH=/opt/wechat-local-ocr/venv/bin:$PATH ./tools/check-local.sh
   

6. Verify WeChat is logged in and the ready main window is at least 700x500.

7. Verify OCR queues are empty.

8. Verify Edge SQLite PRAGMA quick_check returns ok.

Production Cutover

• Use only deploy/scripts/deploy-jwebot-production.sh for normal production cutover.

• The deployer must record both root and user systemd topology, runtime files, configuration, and an online SQLite backup.

• The deployer must disable legacy system OCR services and keep the active production topology to:

  jwebot-edge.service
  wechat-ocr-adaptive-recorder.service
  

• Never skip Edge health, adaptive restart stability, queue, WeChat ready, or SQLite gates.

• If any gate fails, confirm rollback state before retrying.

Mandatory Post-Release Settlement

• After cutover and rollback gates pass, run the installed jwebot_release_update.py.
• The settlement grants exactly 200 Mora to every account that exists at the start of that release settlement and appends a version-labelled account movement.
• Compensation uses the full release string as its idempotency key. Rerunning the same release must not grant Mora twice.
• The tool sends one guarded announcement containing the version, the first changelog bullet, and the Mora x200 compensation notice.
• Announcement state is tracked separately from compensation. A missing or uncertain GUI receipt must never roll back a healthy runtime or trigger another grant.
• If delivery is uncertain, inspect the configured group before using --retry-uncertain-announcement; never retry blindly.
• Production is not complete until the settlement reports success, SQLite quick_check is ok, queues are empty, and service restart counts remain stable.

Backup And Restore

• Pre-deploy and post-deploy baselines must include runtime files, systemd units, environment/configuration, service states, and an online SQLite backup.
• Local and router Restic snapshots must be restored into isolated directories.
• Restore validation requires:
  • sha256sum -c SHA256SUMS;
  • SQLite PRAGMA quick_check;
  • no restore into live paths during validation.

GUI Delivery

• The guarded sender must validate the selected group before drafting and after drafting.
• The sender may click a scaled send-button coordinate first, but must retain a fallback path and visual confirmation.
• Any GUI send optimization must keep:
  • GUI lock acquisition;
  • tokenized draft/send protocol;
  • group fingerprint revalidation;
  • uncertain-delivery quarantine;
  • privacy-safe per-step telemetry.

Telemetry And Reports

• Latency work must preserve or improve per-step telemetry.
• The following stages must be visible when relevant:
  • OCR capture and scan;
  • queue wait and process;
  • Edge routing;
  • fast ACK preparation, GUI send, confirmation, and end-to-end latency;
  • provider generation;
  • final GUI delivery;
  • gui.send.step, gui.bridge.step, and gui.send.total.
• Reports must separate p50/p95 for DeepSeek and OpenClaw when both are used.
• Reports must describe fixed waits, polling intervals, screenshot captures, VNC input actions, and fallback paths in plain Chinese.
• Telemetry must not log message body, sender name, raw group id, reply text, secrets, environment values, or provider payloads.

Plugin Rules

• Registered slash commands must be declared in the ownership inventory.
• Prefer reviewed plugin descriptors plus generated adapters for new commands.
• Run tools/sync-local-extensions.py --check after plugin inventory changes.
• Plugin code must not access GUI, raw SQLite/Ledger, shell, SSH, Docker, environment secrets, or unrestricted network.
• Runtime command ownership freezes at startup. Do not mutate command ownership during request handling.

Access Rules

• External production access uses an operator-provided SSH host alias.
• Root access is obtained by logging in as jwebot and then running su -.
• Do not enable direct root SSH or loosen the jump key no-port-forwarding restrictions without explicit user approval.