# RTK

Repository rules agents must follow for Amanat escrow work.

## Version and Build Numbers

- **Every build of `frontend/` or `backend/` must bump the patch component (`Z` in `X.Y.Z`) by one.** Container images on `git.manko.yoga` are tagged from `package.json` version — a build with an unchanged version overwrites the previous image and erases history. Patch bump on every build, no exceptions.
  - Bump together so frontend and backend stay aligned (e.g. both go `2.6.18 → 2.6.19`).
  - Bumping `Y` (minor) or `X` (major) is only for explicit milestone releases the user requests; never as a side-effect of an ordinary build.
- For any product or code change that affects `frontend/` or `backend/`, bump both versions together before final response in:
  - `frontend/package.json`
  - `frontend/package-lock.json`
  - tracked frontend env files that set `NEXT_PUBLIC_APP_VERSION`
  - `backend/package.json`
  - `backend/package-lock.json`
- Backend runtime/version reporting should read from `backend/package.json`, not a hardcoded fallback.
- Keep frontend and backend on the same version/build number unless the user explicitly asks otherwise.
- Do not bump versions for docs-only changes unless the user asks for a release/build number.
- Mention the resulting frontend and backend version numbers in the final response.

## CI/Build Freeze

- During CI incident diagnosis, do not change Woodpecker pipeline files, Dockerfiles, build scripts, deploy commands, clone strategy, cache behavior, prune behavior, or the production build procedure unless the user explicitly asks for that exact change.
- Diagnose and report the failure first. Classify it as clone/auth, Docker host storage, app build, deploy/compose, notification, or infrastructure before proposing any build-procedure edits.
- Last-known-good build references are backend `5d7d2af1b35d4a595eefc2317a345ba5156fa833` and frontend `ade735281fdb712c026a45947ea52e17a3f8ecdf`.
- Do not add Docker prune, cache cleanup, dependency-install rewrites, or host cleanup blocks to production pipelines without explicit approval. Treat host disk cleanup as an operational action by default.
- Any CI/build change must have explicit user approval, a narrow stated scope, a verification plan, and the required version bump if it will trigger a build or deploy.

## Pre-Deploy CLI Verification

- For any backend or frontend change, run the focused CLI smoke test for the touched area **before pushing a commit that would trigger a build**. The image tracker patch-bumps per build, so a failed build still consumes a version slot.
- Smoke-test scripts live under `backend/scripts/smoke/*.sh` (and the equivalent frontend dir). `scripts/test-*` is in `.gitignore`, so put committed smoke tests in `scripts/smoke/`. They must accept `BASE_URL` so the same script can target a local backend, dev, or production.
- Confirm the script passes against a local backend (or, where local isn't feasible, an explicitly named target) before pushing. After the deploy completes, re-run the same script against the deployed URL to confirm production behavior matches.
- If no smoke-test script exists for the touched area, create one as part of the change.

## CI Notification Safety

- Telegram CI notifications (`appleboy/drone-telegram` in `.woodpecker/*.yml`) must HTML-escape commit messages and strip git trailers (`Co-Authored-By:`, `Signed-off-by:`, `Reviewed-by:`, `Reported-by:`) before sending. Unescaped `<email@addr>` trailers cause "Bad Request: can't parse entities" 400 errors from the Telegram API.
- Use a `compose-notify` shell step that writes the rendered message into `.tgmsg`, then have the telegram plugin send `message_file: .tgmsg`. Do not interpolate `{{commit.message}}` directly into an `html`-formatted message body.
- Woodpecker eats `${VAR}` in command strings — always use `$VAR` (or `$$VAR` to escape) in pipeline command shells.

## Telegram Authentication

- `POST /api/auth/telegram` must allow Telegram Mini App retries with the same signed `initData`; Telegram may reuse launch data across reloads, retries, and duplicate client calls.
- Do not add one-time replay rejection to first-class Telegram login. Use signature verification, `auth_date` freshness, bot rejection, blocked-link checks, and rate limiting for this login path.
- Keep replay/deduplication checks scoped to routes where the payload is actually a one-time operation, such as webhook update handling or explicit Mini App session creation.
- Preserve or add regression tests whenever Telegram auth behavior changes.

## Verification

- Run focused tests for the changed area and a typecheck/build when practical.
- If Redis, email, or other optional infrastructure is unavailable during tests, successful auth paths should fail open only where the production code already treats that dependency as non-critical, and the final response should mention any noisy but non-failing warnings.
- Before final response, report the important verification commands and whether they passed.
