# Release Checklist (සිංහල)

🌐 **Languages:** 🇺🇸 [English](../../../../ops/RELEASE_CHECKLIST.md) · 🇪🇹 [am](../../../am/docs/ops/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../../../ar/docs/ops/RELEASE_CHECKLIST.md) · 🇦🇿 [az](../../../az/docs/ops/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../../../bg/docs/ops/RELEASE_CHECKLIST.md) · 🇧🇩 [bn](../../../bn/docs/ops/RELEASE_CHECKLIST.md) · 🇧🇦 [bs](../../../bs/docs/ops/RELEASE_CHECKLIST.md) · 🇨🇿 [cs](../../../cs/docs/ops/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../../../da/docs/ops/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../../../de/docs/ops/RELEASE_CHECKLIST.md) · 🇬🇷 [el](../../../el/docs/ops/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../../../es/docs/ops/RELEASE_CHECKLIST.md) · 🇪🇪 [et](../../../et/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇷 [fa](../../../fa/docs/ops/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../../../fi/docs/ops/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../../../fr/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇪 [ga](../../../ga/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [gu](../../../gu/docs/ops/RELEASE_CHECKLIST.md) · 🇳🇬 [ha](../../../ha/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../../../he/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [hi](../../../hi/docs/ops/RELEASE_CHECKLIST.md) · 🇭🇷 [hr](../../../hr/docs/ops/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../../../hu/docs/ops/RELEASE_CHECKLIST.md) · 🇦🇲 [hy](../../../hy/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../../../id/docs/ops/RELEASE_CHECKLIST.md) · 🇳🇬 [ig](../../../ig/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../../../it/docs/ops/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../../../ja/docs/ops/RELEASE_CHECKLIST.md) · 🇬🇪 [ka](../../../ka/docs/ops/RELEASE_CHECKLIST.md) · 🇰🇭 [km](../../../km/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [kn](../../../kn/docs/ops/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../../../ko/docs/ops/RELEASE_CHECKLIST.md) · 🇱🇹 [lt](../../../lt/docs/ops/RELEASE_CHECKLIST.md) · 🇱🇻 [lv](../../../lv/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [ml](../../../ml/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [mr](../../../mr/docs/ops/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../../../ms/docs/ops/RELEASE_CHECKLIST.md) · 🇲🇹 [mt](../../../mt/docs/ops/RELEASE_CHECKLIST.md) · 🇲🇲 [my](../../../my/docs/ops/RELEASE_CHECKLIST.md) · 🇳🇵 [ne](../../../ne/docs/ops/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../../../nl/docs/ops/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../../../no/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [or](../../../or/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [pa](../../../pa/docs/ops/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../../../phi/docs/ops/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../../../pl/docs/ops/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../../../pt/docs/ops/RELEASE_CHECKLIST.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../../../ro/docs/ops/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../../../ru/docs/ops/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../../../sk/docs/ops/RELEASE_CHECKLIST.md) · 🇸🇮 [sl](../../../sl/docs/ops/RELEASE_CHECKLIST.md) · 🇷🇸 [sr](../../../sr/docs/ops/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../../../sv/docs/ops/RELEASE_CHECKLIST.md) · 🇰🇪 [sw](../../../sw/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [ta](../../../ta/docs/ops/RELEASE_CHECKLIST.md) · 🇮🇳 [te](../../../te/docs/ops/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../../../th/docs/ops/RELEASE_CHECKLIST.md) · 🇹🇷 [tr](../../../tr/docs/ops/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/RELEASE_CHECKLIST.md) · 🇵🇰 [ur](../../../ur/docs/ops/RELEASE_CHECKLIST.md) · 🇺🇿 [uz](../../../uz/docs/ops/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../../../vi/docs/ops/RELEASE_CHECKLIST.md) · 🇳🇬 [yo](../../../yo/docs/ops/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/RELEASE_CHECKLIST.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/RELEASE_CHECKLIST.md)

---

> **අවසන් වරට යාවත්කාලීන කළේ:** 2026-08-28 — v3.8.51
> ස්වයංක්රීයකරණය සඳහා Claude Code කුසලතා භාවිත කරන සරල කළ නිකුතු ප්රවාහයකි.
>
> **නිකුතු අතරතුර queue/branch එක green තත්ත්වයේ තබා ගන්න:** [RELEASE_GREEN.md](./RELEASE_GREEN.md) බලන්න
> (`/green-prs` පවුල + `npm run check:release-green` + `/babysit` + රාත්රී ධාවනය). මෙය කාලානුරූපව —
> විශේෂයෙන්ම මෙම පිරික්සුම් ලැයිස්තුවට **පෙර** — ධාවනය කිරීමෙන් නිකුතු PR එක green තත්ත්වයෙන් ආරම්භ වේ.

## කෙටියෙන්

```bash
# 1. අනුවාදය ඉහළ නංවා CHANGELOG ජනනය කරන්න (කුසලතාව)
/version-bump-cc patch    # හෝ minor/major

# 2. ගුණාත්මකතා දොරටුව දේශීයව ධාවනය කරන්න
npm run check              # lint + පරීක්ෂණ
npm run test:coverage      # සම්පූර්ණ coverage දොරටුව (60/60/60/60)

# 3. Build කර smoke පරීක්ෂාව සිදු කරන්න
npm run build
npm run test:e2e           # විකල්ප නමුත් නිර්දේශිතයි

# 4. නිකුතුව ජනනය කරන්න (කුසලතාව)
/generate-release-cc

# 5. යොදවන්න (කුසලතාව)
/deploy-vps-both-cc        # හෝ akamai-cc / local-cc

# 6. නිකුතු සාක්ෂි ග්රහණය කරන්න (කුසලතාව)
/capture-release-evidences-cc
```

## npm Trusted Publishing (v3.8.51 සිට පෙරනිමිය) — ඉල්ලීම මත staged, fallback ලෙස direct

`npm-publish.yml` පෙරනිමියෙන් **npm Trusted Publishing (OIDC)** හරහා publish කරයි:
`stage-npm` job එක (github-hosted) එම ධාවනය සඳහා කෙටි කාලීන npm
අක්තපත්රයක් ලබා ගැනීමට GitHub හි id-token එක හුවමාරු කරයි — repository secrets තුළ දිගුකාලීන npm token එකක් නැත, 2FA විමසුමක් නැත, provenance අමුණා ඇත.
2FA මඟහරින tokens ඉවත් කරමින් පවතින බැවින් npm දැන් අනුමත කරන bypass ක්රමය මෙයයි;
WS1.3 සහතිකය පවත්වා ගනිමින්, ව්යාපෘතියට v3.8.48 දක්වා තිබූ සම්පූර්ණ ස්වයංක්රීය ප්රවාහය එය යළි ලබා දෙයි
(කාන්දු වූ token එකකට තනිව publish කළ නොහැක — token එකක්ම නොමැත).

**එක් වරක් පමණක් කරන සැකසුම (හිමිකරු):** npmjs.com → package `omniroute` → Settings → _Trusted
Publisher_ → GitHub: owner `diegosouzapw`, repo `OmniRoute`, workflow `npm-publish.yml`
(environment: none). එය පවතින තුරු ස්වයංක්රීය පියවර `ENEEDAUTH` සමඟ අසාර්ථක වේ:
`publish_mode=staged` (පහත) හෝ `direct` සමඟ නැවත dispatch කරන්න.

### Staged publishing (ඉල්ලීම මත — `publish_mode=staged`)

npm-publish workflow එක තවදුරටත් සෘජුව publish නොකරයි: එය pack කළ tarball එක
boot කර (`check:pack-boot`), ඉන්පසු `npm stage publish` ධාවනය කරයි — එම නිශ්චිත bytes
registry එකේ රඳවා තැබෙන අතර, හිමිකරු අනුමත කරන තෙක් **install කළ නොහැක**.
මානව 2FA දොරටුව සාක්ෂියට පෙර නොව, ඊට පසුවට ගෙන ගොස් ඇත.

**Workflow එක green වූ පසු හිමිකරු අනුගමනය කළ යුතු ප්රවාහය:**

1. `npm stage list omniroute` — stage id එක සොයා ගන්න (එය workflow සාරාංශයේද මුද්රණය වේ).
2. Staged bytes තහවුරු කරන්න (නිර්දේශිතයි): `npm stage download <id>`, ඉන්පසු බාගත්
   tarball එක තාවකාලික prefix එකකට install කර එය boot කරන්න (`npm run check:pack-boot` මඟින්
   CI තුළ එම pack→install→boot තීන්දුවම ස්වයංක්රීය කරයි).
3. `npm stage approve <id>` — 2FA විමසුමම publish කිරීම වේ. `npm stage reject <id>` එය ඉවත දමයි.
4. Publish කිරීමෙන් පසු ආරක්ෂණය: post-publish verifier එක (v3.8.49 සැලැස්මේ WS1.4)
   public registry එකෙන් publish කළ අනුවාදය පිරිසිදු container එකකට install කර එය boot කරයි.

**හදිසි fallback එක:** `publish_mode=direct` සමඟ `workflow_dispatch` භාවිත කිරීමෙන් පැරණි
ක්ෂණික `npm publish` ක්රමය යළි ලබා ගත හැක (staging ක්රියාවලියම වැරදි ලෙස හැසිරේ නම් පමණක් භාවිත කර, හේතුව සටහන් කරන්න).

**එක් වරක් පමණක් කරන ආරක්ෂණ දැඩි කිරීම (හිමිකරු, npmjs.com):** `omniroute` සඳහා
Trusted Publisher එක stage-only මාදිලියෙන් වින්යාස කරන්න. එවිට කාන්දු වූ දිගුකාලීන token එකකට
කිසිදු ස්ථානයකින් සෘජුව `npm publish` කළ නොහැක — CI හට stage කිරීම පමණක් කළ හැකි අතර,
නිකුතුව සිදු කළ හැක්කේ හිමිකරුගේ 2FA මඟින් පමණි.

**බිඳුණු artifact සඳහා ක්රියාමාර්ග සංග්රහය (වෙනස් නොවේ):** පෙරනිමි ක්ෂණික ප්රතිචාරය ලෙස
`npm deprecate omniroute@<bad> "<reason> — use <fixed>"` භාවිත කරන්න (මිනිත්තු කිහිපයකින් කළ හැකි, ආපසු හැරවිය හැකි);
`npm unpublish` භාවිත කළ යුත්තේ පැය 72/no-dependents සීමාව තුළ පමණක් වන අතර, කිසිවිටෙකත් පළමු පියවර ලෙස නොවේ.
Docker: version tag එකක් කිසිවිටෙක නැවත ලියන්න එපා — rollback කිරීම යනු `latest` අවසන් හොඳ digest එක වෙත නැවත යොමු කිරීමයි.

**Docker Hub `latest` (සෑම stable SemVer publish කිරීමකදීම අවශ්යයි):**
`docker-publish` workflow එක විසින් **`X.Y.Z` සහ**, මෙය ඉහළම stable SemVer බවට
`should-promote-latest.sh` එකඟ වන විට, `:latest` යන දෙකම **එකම digest එකෙන්**
tag කළ යුතුය. Job එකෙන් පසු: Hub `latest` digest එක නව SemVer digest එකට සමාන විය යුතු අතර,
`last_updated` ඉදිරියට ගොස් තිබිය යුතුය. Git තුළ පමණක් පවතින නිවැරදි කිරීම් පිළිබඳව
release notes සඳහන් කරන අතරතුර `:latest` පැරණි build එකක තබා නොයන්න.
Compose quickstarts `:latest` භාවිත කරයි; GitOps විසින් `X.Y.Z` pin කිරීම දිගටම කළ යුතුය.
[Docker release channels](../guides/DOCKER_GUIDE.md#release-channels) සහ #10317 බලන්න.

## Hotfix වේගවත් මංතීරුව (ලේබලය `hotfix`)

`hotfix` ලෙස ලේබල් කළ PR එකක් බර CI matrix එක (9-shard E2E, coverage ratchet,
quality-gate, quality-extended) මඟහැර වේගවත්, ඉහළ-සංඥා සහිත ද්වාර තබාගනී: build,
unit shards, integration, vitest, lint/typecheck, docs-sync, `check:pack-artifact`
සහ tarball boot-smoke එක (`check:pack-boot`). ඉලක්කය: ~33min වෙනුවට ≤15min තුළ green වීම.

**ඇතුළත් වීමේ ප්රතිපත්තිය — හතරම අවශ්යයි (Chromium/VS Code/Node හදිසි මංතීරු අනුව ආකෘතිගත කර ඇත):**

1. **බරපතළකම**: production බිඳ වැටී ඇත — ප්රකාශිත artifact එකක් boot වන විට crash වේ /
   ආරක්ෂක නිවැරදි කිරීමක් / release එකේ සෑම පරිශීලකයෙකුටම බලපායි. "වැදගත්" යනු "බිඳ වැටී ඇත" නොවේ.
2. **අධිකාරිය**: `hotfix` ලේබලය යොදන්නේ repository හිමිකරු පමණි. ලේබලයම
   අනුමැතිය වේ — campaign PR එකකදී කිසිවිටෙකත් ස්වයං-සේවාවක් ලෙස නොයොදන්න.
3. **සාක්ෂි**: PR body එක පෙර සම්පූර්ණයෙන්-green වූ heavy run එකට (මඟහැරුණු jobs විසින්
   නැවත වලංගු කරනු ලබන suite එක) සහ fix එකේම අසමත්-වී-ඉන්පසු-සමත් වූ test එකට link කරයි.
4. **විෂය පථය**: cherry-pick පමණි — අවම fix එක, refactors නැත, අමතර වෙනස්කම් නැත.

මඟහැරුණු coverage/ratchet පෘෂ්ඨය release branch එකේ ඊළඟ full run එක මඟින්
නැවත වලංගු කරයි (අඛණ්ඩ release-green) — මංතීරුව මඟහරින්නේ බලා සිටීම පමණි, validation නොවේ.
Tests-පමණක් ඇති diffs (`tests/` යටතේ ඇති සියලු files, `tests/e2e/` යටතේ කිසිවක් නැත) කිසිදු label එකක් නොමැතිව
E2E matrix එක ස්වයංක්රීයව මඟහරියි.

## සවිස්තරාත්මක පිරික්සුම් ලැයිස්තුව

### Release කිරීමට පෙර

- [ ] මෙම release එක ඉලක්ක කරගත් සියලු PRs `release/vX.Y.0` වෙත merge කර ඇත
- [ ] මෙම version එක සඳහා විවෘත සියලු Linear/issue items වසා හෝ ඊළඟ milestone එකට යොමු කර ඇත
- [ ] `release/vX.Y.0` branch එකේ CI green වේ
- [ ] code එකේ `TODO(release)` markers නැත: `grep -r "TODO(release)" src/ open-sse/`
- [ ] Docker base image එක යාවත්කාලීනයි (දැනට `node:24.15.0-trixie-slim`)

### Version සහ Changelog

- [ ] `/version-bump-cc <patch|minor|major>` ධාවනය කරන්න (Claude Code skill)
  - `package.json`, `electron/package.json` හි versions වැඩි කරයි
  - අවසන් tag එකේ සිට git commits මඟින් `CHANGELOG.md` නැවත ජනනය කරයි
  - README.md badges යාවත්කාලීන කරයි
- [ ] CHANGELOG.md අතින් සමාලෝචනය කර අවශ්ය නම් commit messages පිරිසිදු කරන්න
- [ ] `CHANGELOG.md` හි නවතම semver section එක `package.json` version එකට සමාන බව තහවුරු කරන්න
- [ ] ඉදිරි වැඩ සඳහා `## [Unreleased]` පළමු changelog section එක ලෙස තබාගන්න
- [ ] `docs/openapi.yaml` යාවත්කාලීන කරන්න → `info.version` එක `package.json` version එකට සමාන විය යුතුය

### Code ගුණාත්මකභාවය

- [ ] `npm run lint` — errors 0 (warnings පෙර සිට පැවති ඒවාය)
- [ ] `npm run typecheck:core` — clean
- [ ] `npm run typecheck:noimplicit:core` — clean (strict)
- [ ] `npm run check:cycles` — circular deps නැත
- [ ] `npm run check:any-budget:t11` — budget සීමාව තුළ
- [ ] `npm run check:route-validation:t06` — clean
- [ ] `npm run check:node-runtime` — සහාය දක්වන අවම runtime සීමාව සපුරා ඇත (`>=22.22.2 <23`, `>=24.0.0 <27`, `src/shared/utils/nodeRuntimeSupport.ts` හි `SUPPORTED_NODE_RANGE` අනුව; `package.json` හි `engines` සමඟ පෙළගැසී ඇත)

### පරීක්ෂණ

- [ ] `npm run test:unit` — සමත්
- [ ] `npm run test:vitest` — සමත් (MCP server, autoCombo, cache)
- [ ] `npm run test:coverage` — 60/60/60/60 gate එක සපුරා ඇත (statements/lines/functions/branches)
- [ ] `npm run test:integration` — සමත් (වෙනස්කම් DB / handlers ස්පර්ශ කරන්නේ නම්)
- [ ] `npm run test:combo:matrix` — සමත් (combo strategy matrix: පොදු routing strategies 19ම තේරීම් තීරණ නියත ලෙස සනාථ කරයි; combo routing, strategy resolution, හෝ fallback logic ස්පර්ශ කරන විට ධාවනය කරන්න)
- [ ] `RUN_COMBO_LIVE=1 npm run test:combo:live` — **විකල්ප/අතින්** (gate කළ සැබෑ-upstream smoke; VPS `root@192.168.0.15` වෙතින් read-only DB snapshot එකක් ලබාගනී; සැබෑ providers වෙත ප්රවේශ වී credits වැය කරයි; CI තුළ කිසිවිටෙකත් ධාවනය නොවේ; gate එක නොමැතිව පිරිසිදුව මඟහරියි)
- [ ] `npm run test:combo:live:vps` — **විකල්ප/අතින්** (Phase-3 VPS live smoke: සරල Node ESM හරහා සජීවී `.15` server එකට එරෙහි HTTP scenarios 7ක්; `ssh root@192.168.0.15` අවශ්යයි; `__live_test__*` combos පමණක් සාදා/මකයි; සැබෑ providers වෙත ප්රවේශ වේ; CI තුළ කිසිවිටෙකත් ධාවනය නොවේ)
- [ ] `npm run test:e2e` — සමත් (UI වෙනස්කම්)
- [ ] `npm run test:protocols:e2e` — සමත් (MCP/A2A වෙනස්කම්)
- [ ] `npm run test:ecosystem` — සමත්

### Hooks (Husky මඟින් වලංගු කර ඇත)

Husky hooks `.husky/` තුළ ඇති අතර git මෙහෙයුම්වලදී ස්වයංක්රීයව ධාවනය වේ.

- **pre-commit:** `npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11`
- **pre-push:** වේගවත් නියත gates — `npm run check:any-budget:t11 && npm run check:tracked-artifacts` (2026-06-13 දින සක්රිය කරන ලදී). හිතාමතාම `test:unit` ඉවත් කර ඇත (මන්දගාමීය; CI `test-unit` job එකෙන් ආවරණය වේ).
  - release branches push කිරීමට පෙර `npm run test:unit` අතින් ධාවනය කරන්න.

Hook එකක් අසමත් වුවහොත්: යටින් පවතින ගැටලුව නිවැරදි කරන්න, `--no-verify` භාවිතයෙන් මඟ නොහරින්න.

### Conventional Commits

Release එකට අදාළ සියලු commits `type(scope): subject` ආකෘතිය අනුගමනය කළ යුතුය.

**වලංගු types:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `style`, `ci`

**වලංගු scopes:** `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`, `cloud-agent`, `guardrails`, `compression`, `auto-combo`, `resilience`, `providers`, `executors`, `translator`, `domain`, `authz`

Breaking changes: `BREAKING CHANGE:` footer එක එක් කරන්න හෝ scope එකට පසුව `!` එක් කරන්න (උදා. `feat(api)!: drop /v0`).

### ප්රලේඛනය

- [ ] `npm run check:docs-sync` සාර්ථක වේ (pre-commit මඟින් ස්වයංක්රීයව ධාවනය වේ)
- [ ] `npm run check:docs-all` සාර්ථක වේ (සමස්ත පරීක්ෂාව: docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links)
- [ ] `npm run check:env-doc-sync` 0 සමඟ අවසන් වේ — කේතය ↔ `.env.example` ↔ `docs/reference/ENVIRONMENT.md` පරිසර ගිවිසුම නොවෙනස්ව පවතී
- [ ] `npm run check:doc-links` 0 සමඟ අවසන් වේ — ප්රතිව්යුහගත කිරීමෙන් පසු බිඳුණු අභ්යන්තර markdown යොමු නොමැත
- [ ] ගබඩා කිරීමේ/ධාවන කාලයේ වෙනස්වීම් සඳහා `docs/architecture/ARCHITECTURE.md` සමාලෝචනය කර ඇත
- [ ] පරිසර විචල්ය සහ මෙහෙයුම් වෙනස්වීම් සඳහා `docs/guides/TROUBLESHOOTING.md` සමාලෝචනය කර ඇත
- [ ] `.env.example` වෙනස් වී ඇත්නම්: `docs/reference/ENVIRONMENT.md` යාවත්කාලීන කර ඇත
- [ ] නව විශේෂාංගයට UI එකක් තිබේ නම්: `docs/guides/USER_GUIDE.md` එය සඳහන් කරයි
- [ ] නව විශේෂාංගයට API එකක් තිබේ නම්: `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` යාවත්කාලීන කර ඇත
- [ ] නව විශේෂාංගය module එකක් නම්: ඒ සඳහා වෙන් වූ `docs/<MODULE>.md` පවතී
- [ ] මෙය බිඳීම් ඇති කරන වෙනසක් නම්: `docs/guides/TROUBLESHOOTING.md` හි සංක්රමණ සටහනක් ඇත

### i18n

- [ ] `npm run i18n:check` 0 සමඟ අවසන් වේ — පරිවර්තන තත්ත්වය (`.i18n-state.json`) මූලාශ්ර ලේඛන සමඟ සමමුහුර්තව ඇත (දැඩි ප්රකාරයේදී වෙනස්වී ඇති මූලාශ්ර නොමැත; අවසන් මොහොතේ ලේඛන සංශෝධන සඳහා අනතුරු ඇඟවීමේ ප්රකාරයේ උපදේශනය පිළිගත හැකි නමුත්, tag කිරීමට පෙර එය 0 විය යුතුය)
- [ ] `npm run i18n:check-ui-coverage` 0 සමඟ අවසන් වේ — සෑම UI locale එකක්ම 80% ආවරණ අවම සීමාවේ හෝ ඊට ඉහළින් ඇත
- [ ] `npm run i18n:sync-ui:dry` සියලු locale 42 පුරා අස්ථානගත key 0ක් වාර්තා කරයි
- [ ] මූලාශ්ර ඉංග්රීසි ලේඛන වෙනස් වී ඇත්නම්, tag කිරීමට පෙර `npm run i18n:run` ධාවනය කරන්න (`.env` තුළ `OMNIROUTE_TRANSLATION_API_KEY` අවශ්ය වේ)
- [ ] පරිවර්තන දායකත්ව සුළු ඒවා නම් ඊළඟ නිකුතුවට කල් දැමිය හැක (CHANGELOG තුළ හඹා යන්න)

### දත්ත සමුදා සංක්රමණ

- [ ] `src/lib/db/migrations/` තුළ නව ගොනු තිබේ නම්:
  - [ ] සෑම සංක්රමණයක්ම නැවත නැවත ධාවනය කළ හැක (`CREATE TABLE IF NOT EXISTS`, ආදිය)
  - [ ] සංක්රමණ transaction තුළ ආවරණය කර ඇත
  - [ ] නිවැරදිව අංකනය කර ඇත (අනුක්රමයේ හිඩැස් නොමැත)
- [ ] නැවුම් ස්ථාපනයක පරීක්ෂා කරන්න: `~/.omniroute/omniroute.db` මකා `npm run dev` ධාවනය කරන්න
- [ ] පවතින ස්ථාපනයක පරීක්ෂා කරන්න: DB උපස්ථ කර, සංක්රමණය ධාවනය කර, schema එක සත්යාපනය කරන්න
- [ ] සංක්රමණය වගු නැවත ලියන්නේ නම් WAL ගොනු (`-wal`, `-shm`) නිවැරදිව හසුරුවා ඇත

### සැපයුම්කරු නාමාවලිය (Zod මඟින් වලංගු කළ)

- [ ] `src/shared/constants/providers.ts` Zod schema එක පූරණ අවස්ථාවේ වලංගුය
  - [ ] සියලු සැපයුම්කරුවන්ට අවශ්ය ක්ෂේත්ර (`id`, `label`, `kind`, ආදිය) ඇත
  - [ ] නව නොමිලේ සැපයුම්කරුවන් සඳහා `freeNote` සපයා ඇත
  - [ ] OAuth සැපයුම්කරුවන්ගේ `oauthConfig`, `src/lib/oauth/constants/oauth.ts` තුළ ලියාපදිංචි කර ඇත
- [ ] නව සැපයුම්කරුවෙකු එක් කර ඇත්නම්: ඊට අනුරූප executor එක `open-sse/executors/` තුළ ඇත
- [ ] OpenAI නොවන ආකෘතියක් නම්: translator එක `open-sse/translator/` තුළ ඇත
- [ ] Models, `open-sse/config/providerRegistry.ts` තුළ ලියාපදිංචි කර ඇත
- [ ] `tests/unit/` තුළ unit tests මඟින් සැපයුම්කරු වර්ගීකරණය සහ routing ආවරණය කරයි

### ඩෙස්ක්ටොප් (Electron)

`electron/` වෙනස් වී ඇත්නම්:

- [ ] `npm run electron:smoke:packaged` සාර්ථක වේ
- [ ] අවම වශයෙන් `:win`, `:mac`, `:linux` අතරින් එකක් සඳහා builds පරීක්ෂා කර ඇත
- [ ] කේත අත්සන් කිරීම සිදු කරන්නේ නම්, code signing සහතික කල් ඉකුත් වී නොමැත
- [ ] `electron/package.json` අනුවාදය root `package.json` සමඟ ගැළපේ
- [ ] `stable` වෙත නිකුත් කරන්නේ නම්, ස්වයංක්රීය යාවත්කාලීන channel pointer එක යාවත්කාලීන කර ඇත

### Build සැලැස්ම

Repository එක එකිනෙකට වෙනස් output directory තුනක් භාවිත කරයි — ඒවා කිසිවිටෙක පටලවා නොගන්න:

| Directory | අරමුණ                                                                | හඹා යන්නේද?           |
| --------- | -------------------------------------------------------------------- | --------------------- |
| `src/`    | යෙදුම් මූලාශ්රය (TypeScript / TSX)                                   | ඔව්                   |
| `.build/` | Build අතරමැදි ගොනු — `next build` ප්රතිදානය (`distDir`)              | නැත (gitignore කර ඇත) |
| `dist/`   | බෙදාහැරිය හැකි npm bundle එක — `assembleStandalone` මඟින් එකලස් කරයි | නැත (gitignore කර ඇත) |

> **ක්රියාකරු සටහන:** දුරස්ථ VPS image directory එක `/usr/lib/node_modules/omniroute/app/` ලෙසම පවතී.
> වෙනස් වූයේ repository එක **තුළ ඇති** build ප්රතිදානය පමණි (`app/` → `dist/`). Deploy skills මඟින්
> `dist/` අන්තර්ගතය දුරස්ථ `app/` directory එකට rsync කරයි — VPS path වෙනස්කම් අවශ්ය නොවේ.

**තනි-build ප්රවාහය:**

```
npm run build:release
  └─ rm -rf .build dist          (පිරිසිදු කිරීම)
  └─ next build → .build/next/   (අතරමැදි ගොනු)
  └─ assembleStandalone          (standalone + static + public + natives → dist/ වෙත පිටපත් කරයි)
  └─ writes dist/BUILD_SHA       (HEAD sentinel)
```

Deploy සඳහා `npm run build` ධාවනය කර ඉන්පසු වෙනම `npm run build:cli` ධාවනය නොකරන්න — එක් command එකකින් පිරිසිදු rebuild එකක් + sentinel එකක් සිදු කරන
`npm run build:release` භාවිත කරන්න.

### Artifact වලංගුකරණය

- [ ] `npm run build:release` සාර්ථක වන අතර `dist/BUILD_SHA` == `git rev-parse --short HEAD`
- [ ] `npm run check:pack-artifact` පිරිසිදුය — `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, හෝ වෙනත් දේශීය අවශේෂ නොමැත
- [ ] Build කිරීමෙන් පසු `dist/server.js` පවතී
- [ ] විකල්ප දේශීය packaged-runtime smoke පරීක්ෂාව: `npm run dev:candidate -- build` ට පසු `npm run dev:candidate -- validate` මඟින් packed tarball එක හුදකලා `DATA_DIR` එකක ආරම්භ කර `/api/health` + `/v1/models` පරීක්ෂා කරයි ([දායකත්ව Golden Path](CONTRIBUTION_GOLDEN_PATH.md#local-candidate-loop) බලන්න)

### Tag කිරීම සහ නිකුතුව

- [ ] `/generate-release-cc` (Claude Code skill) ධාවනය කරන්න:
  - `vX.Y.Z` tag එක සාදයි
  - Tag එක සහ branch එක push කරයි
  - Changelog අන්තර්ගතය සමඟ GitHub Release එකක් විවෘත කරයි
  - Electron installer අමුණයි (build කර ඇත්නම්)
- [ ] නැතහොත් අතින්:
  ```bash
  git tag -a vX.Y.Z -m "Release vX.Y.Z"
  git push origin vX.Y.Z
  gh release create vX.Y.Z --notes-from-tag
  ```

### Deploy කිරීම

Deploy skills සැහැල්ලු rsync ප්රවාහය භාවිත කරයි — `npm pack` නැත, `npm i -g` නැත:

- [ ] ඉලක්කයට ගැළපෙන යෙදවීමේ කුසලතාව භාවිත කරන්න:
  - `/deploy-vps-local-cc` — දේශීය VPS (192.168.0.15)
  - `/deploy-vps-akamai-cc` — Akamai VPS (69.164.221.35)
  - `/deploy-vps-both-cc` — දෙකම
- [ ] යෙදවීමට පෙර, `dist/BUILD_SHA` == `git rev-parse --short HEAD` බව තහවුරු කරන්න
- [ ] ගොඩනැගීම `node_modules` සැබෑවටම පවතින ස්ථානයක ධාවනය විය යුතුය (ප්රධාන checkout එක හෝ `npm ci` ක්රියාත්මක කළ worktree එකක් — සංකේතාත්මක සබැඳියක් යෙදූ worktree එකක් නොවේ)
- [ ] යෙදවූ instance එකේ මූලික ක්රියාකාරීත්ව පරීක්ෂණයක් සිදු කරන්න:
  - `/dashboard/health` විවෘත කරන්න → අනුවාද පෙළ නිකුතුවට ගැළපෙන බව පරීක්ෂා කරන්න
  - දන්නා provider කෙනෙකු වෙත `/v1/chat/completions` ඉල්ලීමක් ධාවනය කරන්න
  - `/api/monitoring/health` මඟින් `CLOSED` circuit breakers ආපසු ලබා දෙන බව සත්යාපනය කරන්න
  - MCP transports ප්රතිචාර දක්වන බව තහවුරු කරන්න (`/mcp` HTTP, `/mcp-sse` SSE)

### නිකුතුවෙන් පසු

- [ ] `/capture-release-evidences-cc` ධාවනය කරන්න (Claude Code කුසලතාව)
  - නව විශේෂාංගවල WebP තිර රූ/පටිගත කිරීම් ග්රහණය කරයි
  - ඒවා නිකුතු සටහන් / බ්ලොග් සටහනට අමුණයි
- [ ] නිකුතු නිවේදනය සමඟ GitHub Discussions / Discord යාවත්කාලීන කරන්න
- [ ] ඊළඟ අනුවාදය සඳහා milestone එකක් විවෘත කරන්න
- [ ] එය තීරණාත්මක නම්: සාකච්ඡාව pin කරන්න හෝ යෙදුම තුළ banner එක සඳහා `news.json` තුළ පළ කරන්න

### Radar පොදු දියත් කිරීමේ දොරටුව

Radar නිවේදනය හිතාමතාම `active: false` ලෙස commit කර ඇත. පහත සෑම අයිතමයකටම සාක්ෂි සැපයූ පසු සක්රිය කිරීම වෙනම
වෙනස්කමක් ලෙස සිදු කෙරේ:

- [ ] එක මත එක රඳා පවතින සියලු Radar PR ඒකාබද්ධ කර ඇති අතර release-tip CI සාර්ථකය
- [ ] `RADAR_ENABLED` පෙරනිමියෙන් තවමත් අක්රියව තබා OSS Radar routes යෙදවා ඒවායේ මූලික ක්රියාකාරීත්වය පරීක්ෂා කරන්න
- [ ] නම් කරන ලද Radar host එකේ `GET /planos`, `/termos`, `/privacidade`, සහ `/reembolso` සඳහා මූලික ක්රියාකාරීත්ව පරීක්ෂණ සිදු කරන්න
- [ ] ක්රියාකරුගේ අනන්යතාව/සම්බන්ධතා තොරතුරු/ලිපිනය සහ හිමිකරු අනුමත කළ නීතිමය සමාලෝචනය පුද්ගලික සේවාව තුළ සටහන් කරන්න
- [ ] පරීක්ෂණ ප්රකාරයේදී පමණක් Stripe Checkout සහ අත්සන් කළ webhook එක ක්රියාත්මක කර පරීක්ෂා කරන්න
- [ ] අනුමත යවන්නා/domain එක භාවිතයෙන් සංකේතනය කළ එක් ගනුදෙනුමය විද්යුත් තැපැල් බෙදාහැරීමක් ක්රියාත්මක කර පරීක්ෂා කරන්න
- [ ] backup ප්රතිසාධනය සහ අධීක්ෂණය යටතේ, අයවැය සීමා කළ එක් පර්යේෂණ ධාවනයක් සාර්ථක බව ඔප්පු කරන්න
- [ ] පරිත්යාග සාක්ෂි පිළිගැනීමට පෙර BRL/PIX සමාලෝචන ප්රතිපත්තිය අනුමත කරන්න
- [ ] පෙර දොරටු සම්පූර්ණ කළ පසුව පමණක් පොදු Checkout සක්රිය කර, ඉන්පසු නව `news.json` ID එක සක්රිය කරන්න
- [ ] Home banner එක දේශීයකරණය කළ පෙළ භාවිත කරන බවත්, පැරණි ID එකක් ඉවත දැමූ පසු නව ID එකක් නැවත දිස්වන බවත් සත්යාපනය කරන්න

## Embedded Services ස්මෝක් පරීක්ෂාව (v3.8.4+)

Embedded Services වෙනස්කම් ඇතුළත් ඕනෑම නිකුතුවක් බෙදාහැරීමට පෙර, පහත දෑ තහවුරු කරන්න:

### නැවුම්-DB ආරම්භය (migration ගැටීම් හඳුනාගනී — v3.8.4 hotfix එකෙන් පසු එක් කරන ලදී)

- [ ] `DATA_DIR=$(mktemp -d) npm start &` — ආරම්භය සඳහා තත්පර 10ක් රැඳී සිටින්න
- [ ] `curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool'` මඟින් `"9router"` ආපසු ලබා දෙයි (404 නොවේ, 500 නොවේ). migration `071_services.sql` යෙදී ඇති බවත් + පේළිය seed කර ඇති බවත් තහවුරු කරයි.
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(version_manager);" | grep -E "provider_expose|logs_buffer_path|last_sync_at"` මඟින් පේළි 3ක් ආපසු ලබා දෙයි.
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(webhooks);" | grep -E "kind|metadata_encrypted"` මඟින් පේළි 2ක් ආපසු ලබා දෙයි (`070_webhooks_kind_metadata.sql` යෙදී ඇති බව වලංගු කරයි).
- [ ] `node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts` සාර්ථක වේ — අනාගත ගැටීම්වලින් ආරක්ෂා කරයි.

### 9Router

- [ ] `POST /api/services/9router/install` මිනිත්තු 2කට අඩු කාලයකදී `installedVersion` සමඟ 200 ආපසු ලබා දෙයි
- [ ] `POST /api/services/9router/start` තත්පර 30කට අඩු කාලයකදී 200 සහ `state: "running"` ආපසු ලබා දෙයි
- [ ] `GET /api/services/9router/status` මඟින් `health: "healthy"` වාර්තා කරයි
- [ ] `"model": "9router/auto/..."` සමඟ `POST /v1/chat/completions` මඟින් 200 ආපසු ලබා දෙයි (9Router හරහා අන්තයේ සිට අන්තයට routing)
- [ ] `GET /dashboard/providers/services/9router/embed/dashboard` මඟින් proxy එක තුළ 9Router ස්වදේශීය UI එක render කරයි (සෘජු `127.0.0.1:port` iframe එකක් නොමැත)
- [ ] `POST /api/services/9router/rotate-key` මඟින් `{ keyRotated: true }` ආපසු ලබා දෙන අතර සේවාව පිරිසිදුව නැවත ආරම්භ වේ
- [ ] `POST /api/services/9router/stop` මඟින් 200 සහ `state: "stopped"` ආපසු ලබා දෙයි
- [ ] `GET /api/services/9router/logs?tail=50` මඟින් මෑත පේළි අඩංගු `snapshot` event එකක් සහිත SSE stream එකක් ආපසු ලබා දෙයි
- [ ] PATH තුළ `npm` නොමැති පරිසරයක ස්ථාපනය කිරීමේදී හිතකාමී (stack trace නොවන) දෝෂ පණිවිඩයක් සමඟ 500 ආපසු ලබා දෙයි

### CLIProxyAPI

- [ ] `POST /api/services/cliproxy/install` මිනිත්තු 2කට අඩු කාලයකදී 200 ආපසු ලබා දෙයි
- [ ] `POST /api/services/cliproxy/start` තත්පර 30කට අඩු කාලයකදී 200 සහ `state: "running"` ආපසු ලබා දෙයි
- [ ] `GET /api/services/cliproxy/status` මඟින් `health: "healthy"` වාර්තා කරයි
- [ ] `POST /api/services/cliproxy/stop` මඟින් 200 සහ `state: "stopped"` ආපසු ලබා දෙයි
- [ ] `GET /api/services/cliproxy/logs?tail=50` මඟින් SSE stream එකක් ආපසු ලබා දෙයි

### ආරක්ෂක ප්රතිගමනය

- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/9router/start` මඟින් `403 LOCAL_ONLY` ආපසු ලබා දෙයි
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/cliproxy/start` මඟින් `403 LOCAL_ONLY` ආපසු ලබා දෙයි
- [ ] `/api/services/*` වෙතින් ලැබෙන දෝෂ ප්රතිචාරවල `err.stack` හෝ නිරපේක්ෂ ගොනු මාර්ග අඩංගු නොවේ

## v3.8.0+ පරීක්ෂණ

ඕනෑම v3.8.x නිකුතුවක් බෙදාහැරීමට පෙර, මෙම අමතර අයිතම තහවුරු කරන්න:

- [ ] `omniroute --tray` macOS මත ආරම්භ වේ (systray2 `~/.omniroute/runtime/` තුළ ස්ථාපනය කර ඇත)
- [ ] `omniroute --tray` Linux මත ආරම්භ වේ (DISPLAY අවශ්යයි; එය සකසා නොමැති නම් සුමට දෝෂයක්)
- [ ] `omniroute --tray` Windows මත ආරම්භ වේ (PowerShell NotifyIcon, අමතර binaries නොමැත)
- [ ] `omniroute config tray enable` මඟින් ස්වයංක්රීය-ආරම්භක ඇතුළත් කිරීමක් සාදයි; disable මඟින් එය ඉවත් කරයි
- [ ] `npm install -g omniroute@<this-version>` මඟින් මාරාන්තික පිටවීමකින් තොරව postinstall ධාවනය කරයි
- [ ] යාවත්කාලීන මාර්ගය විකල්ප dependencies රඳවා ගනී: `omniroute update --apply` සහ ස්වයංක්රීය යාවත්කාලීනකය
      `npm install -g … --include=optional` ධාවනය කරන බැවින් `optionalDependencies` (better-sqlite3,
      keytar, tls-client, සහ llmlingua SLM stack එක: `@atjsh/llmlingua-2@2.0.5`,
      `js-tiktoken`) යාවත්කාලීනයකින් පසුවත් රඳා පවතී. ultra `modelPath` SLM මට්ටමට ද
      පළමු භාවිතයේදී `${DATA_DIR}/models/llmlingua` වෙත ස්වයංක්රීයව බාගත කරන tinybert model එක අවශ්ය වේ. ඉන්පසු Postinstall
      (`scripts/build/colocateOptionals.mjs`) මඟින් SLM විකල්ප closure එක `dist/node_modules`
      තුළ සම-ස්ථානගත කරයි, එවිට worker එක තනි `@huggingface/transformers` ^4.2.0
      instance එකක් resolve කරයි — standalone trace එක bundle කරන්නේ transformers පමණක් වන අතර, ගතිකව import කරන
      විකල්ප නොවේ; එබැවින් මෙය නොමැතිව worker එක root එකේ transformers සමඟ llmlingua-2 load
      කරන අතර SLM මට්ටම නිහඬව fail-open වේ.
- [ ] `omniroute status` `.env` එකක් නොමැතිව ක්රියා කරයි (CLI token මාර්ගය, loopback පමණි)
- [ ] `curl http://localhost:20128/api/shutdown` මඟින් 401 ආපසු ලබා දෙයි (සැමවිටම-ආරක්ෂිත route එක)
- [ ] `curl -H "host: evil.com" http://localhost:20128/api/mcp/sse` මඟින් 401 ආපසු ලබා දෙයි (loopback guard)
- [ ] පළමු ධාවනයේදී SQLite runtime එක `bundled` ලෙස resolve වේ (bundle කළ binary එක platform එක සඳහා වලංගුය)
- [ ] `node_modules/better-sqlite3` මකා දැමූ විට SQLite runtime එක `runtime` වෙත fallback වේ
- [ ] Smart MCP filter එක සැබෑ `playwright-mcp browser_snapshot` ප්රතිදානය සම්පීඩනය කරයි (≥50% අඩු කිරීමක්)
- [ ] `skills/omniroute*/SKILL.md` ගොනු 10ම raw GitHub URL හරහා පොදුවේ ලබාගත හැකිය
- [ ] නැවුම් පිහිටුවීමකදී onboarding wizard එක "එය ක්රියා කරන ආකාරය" මට්ටම්-සංචාර පියවර පෙන්වයි
- [ ] මුල් dashboard එකේ මට්ටම් ආවරණ widget එක වින්යාස කළ/සක්රිය ගණන් පෙන්වයි

---

## 3.9.0 LTS වෙන් කිරීම (3.8.58 හි පෙරහුරු කරන ලදී)

v3.8.59 ට පසු ඊළඟ අනුවාදය 3.9.0 වන අතර, එහි අග්රය දිගුකාලීන ශාඛා දෙකක් බවට පත්වේ:
`stable/v3` (v3 LTS පෙළ, npm `latest`) සහ `develop` (v4, 4.0.0 දක්වා ඉහළ නංවා ඇත, npm
`nightly`). ශාඛා/නාලිකා ආකෘතිය, ඉදිරියට ගෙනයාම සහ ලේබල
[RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) හි ඇත; සැලැස්ම [ROADMAP](../../ROADMAP.md) හි (අදියර 3) ඇත. වෙන් කිරීම එක් වරක් ක්රියාත්මක වේ;
3.8.58 මඟින් fork එකක් මත එය මුල සිට අග දක්වා පෙරහුරු කරන අතර, 3.8.59
[GO/NO-GO පිරික්සුම් ලැයිස්තුව](./LTS_GO_NO_GO.md) සමඟ අවසන් වේ.

### වියළි ධාවනය (කියවීමට පමණි, ඕනෑම වේලාවක ආරක්ෂිතයි)

```bash
npm run release:dry-run-lts-cut                       # සැබෑ වෙන් කිරීම: HEAD වෙතින් 3.9.0, පෙර ටැගය v3.8.59
npm run release:dry-run-lts-cut -- --from <3.9.0-tip> # මූලාශ්ර commit එක නිශ්චිත කරන්න
```

`scripts/release/dry-run-lts-cut.mjs` කිසිවක් ක්රියාත්මක නොකරයි: එය git සහ `gh` කියවා
සම්පූර්ණ අනුපිළිවෙළ මුද්රණය කරයි — පූර්ව කොන්දේසි (මූලාශ්රය නිරාකරණය වේ, මූලාශ්ර repository එකට සම්පූර්ණ ඉතිහාසය ඇත —
shallow clone එකකට `stable/v3` push කළ නොහැක, පළමු
බද්ධ කළ parent එකේදීම ලැබෙන පාර්ශ්වය pack එක ප්රතික්ෂේප කරයි, එබැවින් සම්පූර්ණ clone එකකින් වෙන් කිරීම සිදු කරන්න, නැතහොත් පළමුව `git fetch --unshallow origin` ක්රියාත්මක කරන්න —
පෙර ටැගය පවතී, `package.json` ඉලක්ක අනුවාදය වේ, `release-freeze` issue එකක් විවෘතව ඇත, පවතින release ශාඛාවක විවෘත
`Release branch not green` issue එකක් නොමැත —
නොපවතින ශාඛාවක් හරිත ලෙස නොව, `?` නොදන්නා ලෙස වාර්තා වේ — Mergify `release` පෝලිම වින්යාස කර ඇත (G11: `queue_rules`, `checks_timeout`,
`queue` ලේබලය), `release/*` ruleset එක තවමත් මකා දැමීම සහ force-push අවහිර කරයි, සහ
`stable/v3` හා `develop` තවම නොපවතී), ශාඛා පියවර දෙක, සක්රිය නොවූ කාර්යප්රවාහවල කුමන
ප්රේරක සහ `if:` කොන්දේසි සත්ය වන්නේද (සහ repository විචල්යයකින් තවමත් අවහිර කර ඇති හෝ
canonical repository එකට නිශ්චිත කර ඇති ඒවා), අපේක්ෂිත dist-tags (`latest` → 3.9.0, `next` සහ
`nightly` හිස්) සහ ආපසු පෙරළීම. පිටවීම `0` = `RESULT: READY`, `1` = අවහිර කරන පූර්ව කොන්දේසියක්
අසාර්ථක විය (`✗`), `2` = භාවිත දෝෂයකි. `--advisory <id,...>` මඟින් පරීක්ෂාවක් සඟවා නොගෙන අනතුරු ඇඟවීමක් (`!`)
දක්වා පහත හෙළයි.

3.9.0 release freeze එක තවමත් විවෘතව තිබියදී සැබෑ වෙන් කිරීමේ වියළි ධාවනය ක්රියාත්මක කරන්න — ශාඛා
ටැගයට පසුව සහ අදියර 12c මඟින් freeze එක ඉවත් කිරීමට පෙර නිර්මාණය කෙරේ.

### 3.8.58 පෙරහුරුව (fork සඳහා පමණි)

```bash
# 1. පෙරහුරු පරාමිති සමඟ වත්මන් අග්රය මත වියළි ධාවනයක් සිදු කරන්න
npm run release:dry-run-lts-cut -- --target-version 3.8.58 --previous-tag v3.8.57 \
  --advisory freeze,base-green

# 2. FORK remote එකකට එරෙහිව ක්රියාත්මක කරන්න (origin, හෝ URL එක canonical
#    repository එක වන ඕනෑම remote එකක් ප්රතික්ෂේප කෙරේ; සෑම පියවරකදීම terminal එකේ තහවුරු කිරීම ඉල්ලයි)
git remote add rehearsal https://github.com/<you>/OmniRoute.git
node scripts/release/dry-run-lts-cut.mjs --execute --remote rehearsal \
  --target-version 3.8.58 --previous-tag v3.8.57 --advisory freeze,base-green

# 3. fork එකේ සක්රිය නොවූ කාර්යප්රවාහ අත්හදා බලන්න (වියළි ධාවනය
#    canonical-repository pin එකක් වාර්තා කරන තැන්වල workflow_dispatch), පසුව ආපසු පෙරළන්න
node scripts/release/dry-run-lts-cut.mjs --execute --rollback --remote rehearsal \
  --target-version 3.8.58 --previous-tag v3.8.57 --advisory freeze,base-green
```

develop වැඩි කිරීමේ commit එක git plumbing භාවිතයෙන් ගොඩනඟයි (working tree එක ස්පර්ශ නොවේ) සහ
cycle-open commit එකක් මෙන් එකම ගොනු පහ වැඩි කරයි: `package.json`, `open-sse/package.json`,
`electron/package.json`, `package-lock.json` සහ `docs/openapi.yaml`. `[4.0.0]`
CHANGELOG කොටස සහ එහි i18n පිටපත්, එහි පළමු
PR එකට පෙර, පසුව `develop` මත විවෘත කෙරේ. script එක කිසිවිටෙක npm dist-tags වෙනස් නොකරයි — ඒවා තාවකාලික පරීක්ෂණ package එකක් මත පෙරහුරු කරන්න.

### PR පෙරදසුන් artifact එක (වරක් ගොඩනඟා, එම bytes ම ප්රවර්ධනය කරන්න)

`.github/workflows/preview-artifact.yml` මඟින් PR head එකකින් එක් production tarball එකක් ගොඩනඟා
එම නිශ්චිත build එක වලංගු කරයි (#8084 කොටස (a)). එකම repository එකේ PR සඳහා පමණි; කිසිවක් publish නොකෙරේ.

```bash
gh workflow run preview-artifact.yml -f pr_number=<N>   # නැතහොත් `preview-artifact` ලේබලය එක් කරන්න
gh run download <run-id> --name preview-artifact-pr<N>-<sha7> --dir preview
cd preview && sha256sum -c SHA256SUMS
gh attestation verify omniroute-*.tgz --repo diegosouzapw/OmniRoute
npm install -g ./omniroute-*.tgz                          # පෙරදසුන් ස්ථාපනය
```

ධාවනය `npm ci`, `npm run build:release`, `npm run check:pack-artifact` ක්රියාත්මක කර, tarball එක
pack කර, `npm run check:pack-boot` (ව්යාජ secrets, තාවකාලික data dir) ක්රියාත්මක කර, නැවත pack කර,
digest එක සමාන නොවේ නම් අසාර්ථක වේ; ඉන්පසු `artifact-identity.json` (head SHA, base
SHA, lockfile hash, platform, arch, node ABI, bundler, build policy —
`scripts/release/artifact-identity.mjs`) වාර්තා කර වෙනම job එකකදී tarball එක සහතික කරයි. පෙරදසුනක්
ප්රවර්ධනය කිරීම යනු එම tarball එක ස්ථාපනය කිරීමයි: මූලාශ්රයෙන් කිසිවිටෙක නැවත ගොඩනඟන්න එපා.

### වෙන් කිරීම (3.9.0, GO පසු)

1. GO [LTS_GO_NO_GO.md](./LTS_GO_NO_GO.md) හි වාර්තා කර ඇත.
2. `npm run release:dry-run-lts-cut -- --from v3.9.0` මඟින් `RESULT: READY` මුද්රණය කරයි.
3. වියළි ධාවනය මුද්රණය කරන විධාන භාවිතයෙන් `origin` මත ශාඛා අතින් නිර්මාණය කරන්න —
   script එක `origin` වෙත push කිරීම ප්රතික්ෂේප කරයි. සමාලෝචනය කළ develop commit එකක් නැවත භාවිත කිරීමට,
   පළමුව ඔබේ fork එකට එරෙහිව 3.9.0 අග්රය මත `--execute` පෙරහුරුව ක්රියාත්මක කරන්න; එය SHA දෙකම මුද්රණය කරන අතර,
   එම commits ම push කළ හැක:

   ```bash
   git push origin <stable-sha>:refs/heads/stable/v3 <develop-sha>:refs/heads/develop
   ```

4. පළමු PR එක ඒකාබද්ධ කිරීමට පෙර `stable/v3` සහ `develop` ආරක්ෂා කරන්න (රීති කට්ටල + ඒකාබද්ධ කිරීමේ පෝලිම).
5. අක්රිය කාර්ය ප්රවාහ ශාඛා පැවතීම මත සක්රිය වේ: `forward-port.yml` (`stable/v3` වෙත push කිරීම),
   `validate-stable-pr.yml` (`stable/v3` වෙත PR) සහ `nightly-v4-build.yml`
   (`develop` ගොඩනඟයි). සජීවී කිරීමට පෙර, `secrets.FORWARD_PORT_TOKEN` repository secret එක සකසන්න (එවිට
   ඉදිරියට-port කරන PR මත CI ක්රියාත්මක වේ); හිමිකරු repository
   variable එක වන `vars.NIGHTLY_PUBLISH`, `true` ලෙස සකසා npm Trusted Publishing විසින්
   `nightly-v4-build.yml` පිළිගන්නා තෙක් රාත්රී ප්රකාශනය අක්රියව පවතී. නාලිකා නිර්ණය `scripts/release/dist-tag.mjs` මඟින් සිදු වේ; එය
   `npm-publish.yml` භාවිත කරන නිර්ණයකයම වේ.
6. නාලිකා සත්යාපනය කරන්න: `npm view omniroute dist-tags --json` මඟින් `latest` = 3.9.0 ලෙසත්, v4 ප්රකාශනය වන තෙක්
   `next` / `nightly` නොමැති බවත් පෙන්වයි.
7. අවශ්ය නම් ආපසු හැරවීම: `git push origin --delete refs/heads/stable/v3 refs/heads/develop`
   සහ `npm dist-tag add omniroute@3.8.59 latest`.

---

## ආපසු හැරවීම

නිකුතුවේ බරපතළ ගැටලුවක් තිබේ නම්:

1. `gh release edit vX.Y.Z --prerelease` (නවතම නිකුතුව නොවන ලෙස සලකුණු කරයි)
2. `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z` (පරිශීලකයන් තවමත් එය භාවිතයට ගෙන නොමැති නම් පමණි)
3. හෝ: `release/vX.Y.0` මත hotfix එකක් → patch නිකුතුව `vX.Y.(Z+1)`
4. GitHub Discussions සහ Discord තුළ වහාම දැනුම් දෙන්න

## දැඩි නීති

- කිසිවිටෙකත් `main` වෙත සෘජුව commit නොකරන්න
- කිසිවිටෙකත් `main` හෝ `release/*` branches වෙත `git push --force` භාවිත නොකරන්න
- කිසිවිටෙකත් Husky hooks (`--no-verify`) මඟ නොහරින්න
- කිසිවිටෙකත් secrets, credentials, හෝ `.env` files commit නොකරන්න
- Coverage අගය ≥60/60/60/60 (statements/lines/functions/branches) ලෙස පවත්වාගත යුතුය
- `src/`, `open-sse/`, `electron/`, හෝ `bin/` තුළ production code වෙනස් කරන විට සැමවිටම tests ඇතුළත් කරන්න හෝ යාවත්කාලීන කරන්න

## ස්වයංක්රීය සමමුහුර්ත පරීක්ෂාව

PR එකක් විවෘත කිරීමට පෙර docs sync guard එක locally ධාවනය කරන්න:

```bash
npm run check:docs-sync
```

CI ද `.github/workflows/ci.yml` තුළ මෙම පරීක්ෂාව ධාවනය කරයි (lint job එක).