# Release Checklist (አማርኛ)

🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇱🇰 [si](../../../si/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 አረንጓዴ እንደሆነ ያቆዩ:** [RELEASE_GREEN.md](./RELEASE_GREEN.md)ን ይመልከቱ
> (`/green-prs` ቤተሰብ + `npm run check:release-green` + `/babysit` + የሌሊት ሩጫ)። ይህን
> በየጊዜው — በተለይም ከዚህ የማረጋገጫ ዝርዝር **በፊት** — ማስኬድ የልቀት PR አረንጓዴ ሆኖ እንዲጀምር ያደርጋል።

## በአጭሩ

```bash
# 1. ስሪቱን ያሳድጉ + CHANGELOG ይፍጠሩ (ክህሎት)
/version-bump-cc patch    # ወይም minor/major

# 2. የጥራት መፈተሻውን በአካባቢዎ ያስኪዱ
npm run check              # lint + ሙከራዎች
npm run test:coverage      # ሙሉ የሽፋን መፈተሻ (60/60/60/60)

# 3. ይገንቡ እና መሠረታዊ ሙከራ ያድርጉ
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 ጀምሮ ነባሪ) — ሲጠየቅ በደረጃ፣ እንደ አማራጭ በቀጥታ

`npm-publish.yml` በነባሪ በ**npm Trusted Publishing (OIDC)** በኩል ያትማል፦
`stage-npm` ሥራው (በGitHub የሚስተናገድ) የGitHubን id-token ለዚያ ሩጫ አጭር ዕድሜ ካለው የnpm
ማረጋገጫ መረጃ ጋር ይለዋወጣል — በrepository secrets ውስጥ ረጅም ዕድሜ ያለው የnpm token የለም፣ የ2FA ጥያቄ የለም፣ provenance ተያይዟል።
2FAን የሚያልፉ tokens ከአገልግሎት እየወጡ በመሆናቸው፣ አሁን npm የሚፈቅደው ማለፊያ ይህ ነው፤
የWS1.3 ዋስትናን እየጠበቀ (የወጣ token ብቻውን ማተም አይችልም — token የለም) ፕሮጀክቱ እስከ v3.8.48
ድረስ የነበረውን ሙሉ በሙሉ ራስ-ሰር ሂደት ይመልሳል።

**የአንድ ጊዜ ቅንብር (ባለቤት):** npmjs.com → package `omniroute` → Settings → _Trusted
Publisher_ → GitHub: owner `diegosouzapw`, repo `OmniRoute`, workflow `npm-publish.yml`
(environment: የለም)። ይህ እስኪኖር ድረስ ራስ-ሰር ደረጃው በ`ENEEDAUTH` ይወድቃል፦
በ`publish_mode=staged` (ከታች) ወይም `direct` እንደገና ያስጀምሩ።

### በደረጃ ማተም (ሲጠየቅ — `publish_mode=staged`)

የnpm-publish workflow ከእንግዲህ በቀጥታ አያትምም፦ የታሸገውን tarball
(`check:pack-boot`) አስነስቶ `npm stage publish`ን ያስኬዳል — ትክክለኛዎቹ bytes በregistry ላይ
ይቀመጣሉ፣ ባለቤቱ እስኪያጸድቅ ድረስ **ሊጫኑ አይችሉም**። የሰው የ2FA መፈተሻ
ከማስረጃው በፊት ሳይሆን ወደ በኋላ ተዛውሯል።

**workflow አረንጓዴ ከሆነ በኋላ የባለቤቱ ሂደት:**

1. `npm stage list omniroute` — የstage idውን ያግኙ (በworkflow ማጠቃለያ ውስጥም ይታተማል)።
2. በደረጃ የተቀመጡትን bytes ያረጋግጡ (ይመከራል)፦ `npm stage download <id>`፣ ከዚያ የወረደውን
   tarball በጊዜያዊ prefix ውስጥ ጭነው ያስነሱት (`npm run check:pack-boot` በCI ውስጥ
   ተመሳሳዩን pack→install→boot ውሳኔ በራስ-ሰር ያከናውናል)።
3. `npm stage approve <id>` — የ2FA ጥያቄው ራሱ ህትመቱ ነው። `npm stage reject <id>` ያስወግደዋል።
4. ከህትመት በኋላ ያለው የደኅንነት መረብ፦ ከህትመት በኋላ ያለው አረጋጋጭ (የv3.8.49 ዕቅድ WS1.4)
   የታተመውን ስሪት ከይፋዊው registry በንጹሕ container ውስጥ ጭኖ ያስነሳዋል።

**የአደጋ ጊዜ አማራጭ:** `workflow_dispatch` ከ`publish_mode=direct` ጋር የቀድሞውን
ፈጣን `npm publish` ይመልሳል (ይህን በደረጃ ማተሙ ራሱ በትክክል ካልሠራ ብቻ ይጠቀሙ፤ ምክንያቱን ይመዝግቡ)።

**የአንድ ጊዜ ማጠናከሪያ (ባለቤት፣ npmjs.com):** የወጣ ረጅም ዕድሜ ያለው token ከየትኛውም ቦታ
በቀጥታ `npm publish` ማድረግ እንዳይችል፣ Trusted Publisherን ለ`omniroute`
በstage-only ሁነታ ያዋቅሩ — CI በደረጃ ማስቀመጥ ብቻ ይችላል፤ የሚለቀቀው በባለቤቱ 2FA ብቻ ነው።

**የተበላሸ artifact መመሪያ (ያልተቀየረ):** `npm deprecate omniroute@<bad> "<reason> — use <fixed>"`
እንደ ነባሪ ፈጣን እርምጃ ይጠቀሙ (ደቂቃዎች፣ ሊቀለበስ የሚችል)፤ `npm unpublish`ን በ72h/no-dependents
መስኮት ውስጥ ብቻ ይጠቀሙ፣ እንዲሁም ፈጽሞ እንደ መጀመሪያ እርምጃ አይጠቀሙት። Docker፦ የስሪት tagን ፈጽሞ እንደገና አይጻፉ — rollback ማለት
`latest`ን ወደ መጨረሻው ጥሩ digest እንደገና ማመልከት ነው።

**Docker Hub `latest` (በእያንዳንዱ የተረጋጋ SemVer ህትመት ላይ ያስፈልጋል):**
`docker-publish` workflow **ሁለቱንም** `X.Y.Z` እና፣
`should-promote-latest.sh` ይህ ከፍተኛው የተረጋጋ SemVer መሆኑን ሲስማማ፣ `:latest`ን
በ**ተመሳሳይ digest** tag ማድረግ አለበት። ከሥራው በኋላ፦ የHub `latest` digest ከአዲሱ
SemVer digest ጋር እኩል መሆን እና `last_updated` መለወጥ አለበት። የልቀት ማስታወሻዎች በgit ላይ ብቻ
ስላሉ ማስተካከያዎች እያብራሩ፣ `:latest`ን በአሮጌ build ላይ አይተዉ። Compose
quickstarts `:latest`ን ይጠቀማሉ፤ GitOps `X.Y.Z`ን pin ማድረጉን መቀጠል አለበት።
[የDocker ልቀት ቻናሎች](../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 ውስጥ አረንጓዴ መሆን።

**የመግቢያ ፖሊሲ — አራቱም ያስፈልጋሉ (በChromium/VS Code/Node የአደጋ ጊዜ መስመሮች ተምሳሌትነት የተቀረጸ)፦**

1. **ክብደት**፦ production ተበላሽቷል — የታተመ artifact ሲነሳ ይበላሻል / የደህንነት
   ማስተካከያ / ሁሉም የrelease ተጠቃሚዎች ተጎድተዋል። "አስፈላጊ" ማለት "የተበላሸ" ማለት አይደለም።
2. **ሥልጣን**፦ የ`hotfix` መለያውን የሚያደርገው የrepository ባለቤት ብቻ ነው። መለያው ራሱ
   ማጽደቁ ነው — በcampaign PR ላይ በራስዎ አይጠቀሙበት።
3. **ማስረጃ**፦ የPR ይዘቱ ቀዳሚውን ሙሉ በሙሉ አረንጓዴ የሆነ heavy run (የተዘለሉት jobs
   ዳግም የሚያረጋግጡትን suite) እና የማስተካከያውን የራሱን መጀመሪያ ወድቆ ከዚያ ያለፈ test ያገናኛል።
4. **ወሰን**፦ cherry-pick-only — አነስተኛው ማስተካከያ ብቻ፣ refactor የለም፣ አብረው የሚገቡ ሌሎች ለውጦች የሉም።

የተዘለለው coverage/ratchet ወሰን በrelease branch ላይ በሚቀጥለው ሙሉ run
ዳግም ይረጋገጣል (continuous release-green) — መስመሩ የሚዘለው መጠበቅን እንጂ ማረጋገጥን ፈጽሞ አይደለም።
የtests ብቻ ልዩነቶች (ሁሉም ፋይሎች በ`tests/` ስር፣ አንዳቸውም በ`tests/e2e/` ስር ያልሆኑ)
ምንም መለያ ሳያስፈልጋቸው E2E matrixን በራስ-ሰር ይዘላሉ።

## ዝርዝር የማረጋገጫ ዝርዝር

### ከRelease በፊት

- [ ] ለዚህ release የታለሙ ሁሉም PRs ወደ `release/vX.Y.0` ተዋህደዋል
- [ ] ለዚህ version ሁሉም ክፍት Linear/issue ንጥሎች ተዘግተዋል ወይም ወደ ቀጣዩ milestone ተላልፈዋል
- [ ] CI በ`release/vX.Y.0` branch ላይ አረንጓዴ ነው
- [ ] በcode ውስጥ የ`TODO(release)` ምልክቶች የሉም፦ `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`ን ያሳድጋል
  - ከመጨረሻው tag በኋላ ካሉ git commits `CHANGELOG.md`ን ዳግም ያመነጫል
  - የREADME.md badgesን ያዘምናል
- [ ] CHANGELOG.mdን በእጅ ይገምግሙ እና ካስፈለገ commit messagesን ያጽዱ
- [ ] በ`CHANGELOG.md` ውስጥ ያለው የቅርብ ጊዜ semver ክፍል ከ`package.json` version ጋር እኩል መሆኑን ያረጋግጡ
- [ ] ለሚመጣው ሥራ `## [Unreleased]`ን እንደ መጀመሪያው changelog ክፍል ያቆዩ
- [ ] `docs/openapi.yaml`ን ያዘምኑ → `info.version` ከ`package.json` version ጋር እኩል መሆን አለበት

### የCode ጥራት

- [ ] `npm run lint` — 0 errors (warnings ከዚህ በፊት የነበሩ ናቸው)
- [ ] `npm run typecheck:core` — ንጹሕ
- [ ] `npm run typecheck:noimplicit:core` — ንጹሕ (strict)
- [ ] `npm run check:cycles` — circular deps የሉም
- [ ] `npm run check:any-budget:t11` — በbudget ውስጥ
- [ ] `npm run check:route-validation:t06` — ንጹሕ
- [ ] `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` ጋር የተጣጣመ)

### Testing

- [ ] `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፦ የሁሉም 19 public routing strategies የምርጫ ውሳኔዎችን በተወሰነ ሁኔታ ያረጋግጣል፤ 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፦ በplain Node ESM በኩል በlive `.15` server ላይ 7 HTTP scenarios፤ `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 operations ጊዜ በራስ-ሰር ይሄዳሉ።

- **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ን ከመግፋትዎ በፊት `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`)።

### Documentation

- [ ] `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` መካከል ያለው የ env ውል እንዳልተበላሸ ያረጋግጣል
- [ ] `npm run check:doc-links` በ 0 ይወጣል — ከመልሶ ማዋቀር በኋላ የተበላሹ ውስጣዊ markdown ማጣቀሻዎች የሉም
- [ ] `docs/architecture/ARCHITECTURE.md` ለማከማቻ/የአሂድ ጊዜ ልዩነት ተገምግሟል
- [ ] `docs/guides/TROUBLESHOOTING.md` ለ env var እና ለአሠራር ልዩነት ተገምግሟል
- [ ] `.env.example` ከተቀየረ፦ `docs/reference/ENVIRONMENT.md` ተዘምኗል
- [ ] አዲሱ ባህሪ UI ካለው፦ `docs/guides/USER_GUIDE.md` ይጠቅሰዋል
- [ ] አዲሱ ባህሪ API ካለው፦ `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` ተዘምነዋል
- [ ] አዲሱ ባህሪ ሞጁል ከሆነ፦ ለእሱ የተለየ `docs/<MODULE>.md` አለ
- [ ] ተኳሃኝነትን የሚያቋርጥ ለውጥ ከሆነ፦ `docs/guides/TROUBLESHOOTING.md` የፍልሰት ማስታወሻ አለው

### i18n

- [ ] `npm run i18n:check` በ 0 ይወጣል — የትርጉም ሁኔታው (`.i18n-state.json`) ከምንጭ ሰነዶች ጋር ተመሳስሏል (በ strict mode የተለያዩ ምንጮች የሉም፤ ለመጨረሻ ደቂቃ የሰነድ ማስተካከያዎች የ warn-mode ምክር ተቀባይነት አለው፣ ነገር ግን tag ከማድረግ በፊት 0 መሆን አለበት)
- [ ] `npm run i18n:check-ui-coverage` በ 0 ይወጣል — እያንዳንዱ UI locale ቢያንስ 80% የሽፋን ወለል ላይ ወይም ከዚያ በላይ ነው
- [ ] `npm run i18n:sync-ui:dry` በሁሉም 42 locales ውስጥ 0 የጎደሉ keys እንዳሉ ሪፖርት ያደርጋል
- [ ] የእንግሊዝኛ ምንጭ ሰነዶች ከተቀየሩ፣ tag ከማድረግ በፊት `npm run i18n:run` ያሂዱ (በ `.env` ውስጥ `OMNIROUTE_TRANSLATION_API_KEY` ያስፈልጋል)
- [ ] የትርጉም አስተዋጽኦዎች አነስተኛ ከሆኑ ወደ ቀጣዩ release ሊራዘሙ ይችላሉ (በ CHANGELOG ውስጥ ይከታተሉ)

### የውሂብ ጎታ ፍልሰቶች

- [ ] `src/lib/db/migrations/` አዲስ ፋይሎች ካሉት፦
  - [ ] እያንዳንዱ migration idempotent ነው (`CREATE TABLE IF NOT EXISTS`፣ ወዘተ)
  - [ ] Migrations በ transactions ውስጥ ተጠቃለዋል
  - [ ] በትክክል ተቆጥረዋል (በቅደም ተከተሉ ውስጥ ክፍተት የለም)
- [ ] በአዲስ ጭነት ላይ ይፈትሹ፦ `~/.omniroute/omniroute.db`ን ሰርዘው `npm run dev`ን ያሂዱ
- [ ] በነባር ጭነት ላይ ይፈትሹ፦ DBን ምትኬ ያስቀምጡ፣ migrationን ያሂዱ፣ schemaውን ያረጋግጡ
- [ ] Migration ሰንጠረዦችን እንደገና የሚጽፍ ከሆነ WAL ፋይሎች (`-wal`፣ `-shm`) በትክክል ተይዘዋል

### የአቅራቢዎች ካታሎግ (በ Zod የተረጋገጠ)

- [ ] `src/shared/constants/providers.ts` Zod schema በመጫኛ ጊዜ ትክክለኛ ነው
  - [ ] ሁሉም providers አስፈላጊ fields (`id`፣ `label`፣ `kind`፣ ወዘተ) አሏቸው
  - [ ] ለአዲስ ነጻ providers `freeNote` ቀርቧል
  - [ ] OAuth providers `oauthConfig`ን በ `src/lib/oauth/constants/oauth.ts` ውስጥ አስመዝግበዋል
- [ ] አዲስ provider ከታከለ፦ ተዛማጅ executor በ `open-sse/executors/` ውስጥ አለ
- [ ] OpenAI ያልሆነ ቅርጸት ከሆነ፦ translator በ `open-sse/translator/` ውስጥ አለ
- [ ] Models በ `open-sse/config/providerRegistry.ts` ውስጥ ተመዝግበዋል
- [ ] በ `tests/unit/` ውስጥ ያሉ unit tests የprovider ምደባን እና routingን ይሸፍናሉ

### ዴስክቶፕ (Electron)

`electron/` ከተቀየረ፦

- [ ] `npm run electron:smoke:packaged` ያልፋል
- [ ] Builds ቢያንስ ለ`:win`፣ `:mac`፣ `:linux` ከሚሉት ለአንዱ ተፈትሸዋል
- [ ] የኮድ መፈረሚያ certs ጊዜያቸው አላለፈም (ፊርማ ከሚደረግ)
- [ ] የ`electron/package.json` version ከዋናው `package.json` ጋር ይዛመዳል
- [ ] ወደ `stable` release የሚደረግ ከሆነ የራስ-ሰር ማዘመኛ channel pointer ተዘምኗል

### የBuild አቀማመጥ

Repositoryው ሦስት የተለያዩ የውጤት directories ይጠቀማል — ፈጽሞ አታደባልቋቸው፦

| Directory | ዓላማ                                               | ይከታተላል?         |
| --------- | ------------------------------------------------- | --------------- |
| `src/`    | የመተግበሪያ ምንጭ (TypeScript / TSX)                    | አዎ              |
| `.build/` | የBuild መካከለኛ ውጤቶች — የ`next build` ውጤት (`distDir`) | አይ (gitignored) |
| `dist/`   | ለመላክ ዝግጁ የnpm ጥቅል — በ`assembleStandalone` የሚዋቀር   | አይ (gitignored) |

> **የኦፕሬተር ማስታወሻ፦** የርቀት VPS image directory አሁንም `/usr/lib/node_modules/omniroute/app/` ነው።
> የተንቀሳቀሰው **በrepository ውስጥ ያለው** የbuild ውጤት ብቻ ነው (`app/` → `dist/`)። የdeploy skills
> የ`dist/` ይዘቶችን ወደ ርቀት `app/` dir በ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 መጠበቂያ ምልክት)
```

ለdeploy `npm run build`ን ካስኬዱ በኋላ የተለየ `npm run build:cli` አያሂዱ — ይልቁንም
በአንድ command ንጹሕ ዳግም build + 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` አለ

### Tag ማድረግ እና Release

- [ ] `/generate-release-cc`ን ያሂዱ (Claude Code skill)፦
  - `vX.Y.Z` tag ይፈጥራል
  - Tagን እና branchን ይገፋል
  - የchangelog ይዘት ያለው GitHub Release ይከፍታል
  - Electron installersን ያያይዛል (ከተገነቡ)
- [ ] ወይም በእጅ፦
  ```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 skill ይጠቀሙ፦
  - `/deploy-vps-local-cc` — የአካባቢ VPS (192.168.0.15)
  - `/deploy-vps-akamai-cc` — Akamai VPS (69.164.221.35)
  - `/deploy-vps-both-cc` — ሁለቱም
- [ ] Deploy ከማድረግዎ በፊት `dist/BUILD_SHA` == `git rev-parse --short HEAD` መሆኑን ያረጋግጡ
- [ ] Build የሚከናወነው `node_modules` እውነተኛ በሆነበት ቦታ መሆን አለበት (ዋና checkout ወይም `npm ci` የተካሄደበት worktree — symlink የተደረገ worktree አይደለም)
- [ ] Deploy የተደረገውን instance smoke test ያድርጉ፦
  - `/dashboard/health`ን ይክፈቱ → የversion string ከreleaseው ጋር መዛመዱን ያረጋግጡ
  - በሚታወቅ provider ላይ የ`/v1/chat/completions` request ያሂዱ
  - `/api/monitoring/health` `CLOSED` circuit breakersን እንደሚመልስ ያረጋግጡ
  - MCP transports ምላሽ እንደሚሰጡ ያረጋግጡ (`/mcp` HTTP፣ `/mcp-sse` SSE)

### ከRelease በኋላ

- [ ] `/capture-release-evidences-cc`ን ያስኪዱ (Claude Code ክህሎት)
  - የአዳዲስ ባህሪያትን WebP ቅጽበታዊ ምስሎች/ቀረጻዎች ይይዛል
  - ከልቀት ማስታወሻዎች / የብሎግ ልጥፍ ጋር ያያይዛል
- [ ] GitHub Discussions / Discordን በልቀት ማስታወቂያው ያዘምኑ
- [ ] ለሚቀጥለው ስሪት የጊዜ ምዕራፍ ይክፈቱ
- [ ] ወሳኝ ከሆነ፦ ውይይቱን ከላይ ይሰኩ ወይም ለመተግበሪያ ውስጥ ባነር በ`news.json` ውስጥ ይለጥፉ

### የRadar ይፋዊ ማስጀመሪያ መግቢያ መስፈርት

የRadar ማስታወቂያው ሆን ተብሎ `active: false` በሚል ተመዝግቧል። ማግበር ከታች ያለው እያንዳንዱ ንጥል
በማስረጃ ከተረጋገጠ በኋላ የሚደረግ የተለየ ለውጥ ነው፦

- [ ] ሁሉም ተደራራቢ የRadar PRዎች ተዋህደዋል፣ እና የrelease-tip CI አረንጓዴ ነው
- [ ] `RADAR_ENABLED` በነባሪ እንደተዘጋ ሆኖ የOSS Radar መስመሮችን ያሰማሩ እና የጭስ ሙከራ ያድርጉ
- [ ] በተሰየመው የRadar አስተናጋጅ ላይ `GET /planos`፣ `/termos`፣ `/privacidade` እና `/reembolso` የጭስ ሙከራ ያድርጉ
- [ ] በግል አገልግሎቱ ውስጥ የኦፕሬተሩን ማንነት/የመገኛ መረጃ/አድራሻ እና በባለቤቱ የጸደቀ ሕጋዊ ግምገማ ይመዝግቡ
- [ ] Stripe Checkoutን እና የተፈረመውን webhook በሙከራ ሁነታ ብቻ ይሞክሩ
- [ ] በተፈቀደው ላኪ/ዶሜይን አንድ የተመሰጠረ የግብይት ኢሜይል መላክን ይሞክሩ
- [ ] የመጠባበቂያ ቅጂ መልሶ ማግኘትን እና አንድ ክትትል የሚደረግበት፣ በበጀት ጣሪያ የተገደበ የምርምር አሂድን በማስረጃ ያረጋግጡ
- [ ] የልገሳ ማስረጃን ከመቀበልዎ በፊት የBRL/PIX ግምገማ ፖሊሲን ያጽድቁ
- [ ] ይፋዊ Checkoutን ከዚህ በፊት ያሉት መግቢያ መስፈርቶች ከተሟሉ በኋላ ብቻ ያንቁ፣ ከዚያም አዲሱን የ`news.json` ID ያግብሩ
- [ ] የHome ባነሩ አካባቢያዊ የተደረገ ጽሑፍ እንደሚጠቀም እና አሮጌ ID ውድቅ ከተደረገ በኋላ አዲስ ID እንደገና እንደሚታይ ያረጋግጡ

## የተካተቱ አገልግሎቶች ፈጣን ሙከራ (v3.8.4+)

የተካተቱ አገልግሎቶች ለውጦችን የሚያካትት ማንኛውንም ልቀት ከማሰራጨትዎ በፊት የሚከተሉትን ያረጋግጡ፦

### በአዲስ DB ማስነሳት (የማይግሬሽን ግጭቶችን ይለያል — ከv3.8.4 አስቸኳይ ማስተካከያ በኋላ የታከለ)

- [ ] `DATA_DIR=$(mktemp -d) npm start &` — ለማስነሳቱ 10 ሰከንድ ይጠብቁ
- [ ] `curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool'` `"9router"` ይመልሳል (404 አይደለም፣ 500 አይደለም)። ማይግሬሽን `071_services.sql` መተግበሩን እና ረድፉ በመነሻ ውሂብ መሞላቱን ያረጋግጣል።
- [ ] `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"` መሆኑን ዘገባ ያቀርባል
- [ ] `POST /v1/chat/completions` ከ`"model": "9router/auto/..."` ጋር 200 ይመልሳል (በ9Router በኩል ከጫፍ እስከ ጫፍ ማዘዋወር)
- [ ] `GET /dashboard/providers/services/9router/embed/dashboard` የ9Router ቤተኛ UIን በፕሮክሲው ውስጥ ያሳያል (ቀጥተኛ `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` ክስተት ያለውን SSE ዥረት ይመልሳል
- [ ] PATH ውስጥ `npm` በሌለበት አካባቢ መጫን ለተጠቃሚ ምቹ የሆነ (የስታክ መከታተያ ያልሆነ) የስህተት መልዕክት ያለው 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 ዥረት ይመልሳል

### የደህንነት ወደኋላ መመለስ ሙከራ

- [ ] `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፣ ምንም ተጨማሪ ባይነሪዎች የሉም)
- [ ] `omniroute config tray enable` ራስ-ሰር የመነሻ ግቤት ይፈጥራል፤ ማሰናከል ያስወግደዋል
- [ ] `npm install -g omniroute@<this-version>` ከጫና በኋላ ያለ ከባድ መውጫ ይሰራል
- [ ] የማዘመኛ ዱካው አማራጭ ጥገኞችን ይይዛል፦ `omniroute update --apply` እና ራስ-ሰር አዘማኙ
      `npm install -g … --include=optional`ን ያስኬዳሉ፣ ስለዚህ `optionalDependencies` (better-sqlite3,
      keytar, tls-client፣ እና llmlingua SLM ስብስብ፦ `@atjsh/llmlingua-2@2.0.5`,
      `js-tiktoken`) ከማዘመኛ በኋላ እንደተጠበቁ ይቆያሉ። የultra `modelPath` SLM ደረጃ tinybert
      ሞዴልንም ያስፈልገዋል፣ ይህም ለመጀመሪያ ጊዜ ሲጠቀሙበት በራስ-ሰር ወደ `${DATA_DIR}/models/llmlingua` ይወርዳል። ከጫና በኋላ
      (`scripts/build/colocateOptionals.mjs`) የSLM አማራጭ ጥገኝነት ስብስቡን ወደ
      `dist/node_modules` ያስቀምጣል፣ ስለዚህ workerው አንድ ብቻ `@huggingface/transformers` ^4.2.0
      ኢንስታንስ ይፈታል — ራሱን የቻለው የመከታተያ ጥቅል transformersን ብቻ ያካትታል፣ በተለዋዋጭ ሁኔታ የሚገቡትን
      አማራጮች ግን አያካትትም፤ ስለዚህ ይህ ከሌለ workerው llmlingua-2ን ከroot transformers ጋር
      ይጭናል፣ እና የSLM ደረጃው ያለማሳወቂያ ክፍት ሆኖ ይወድቃል።
- [ ] `omniroute status` ያለ `.env` ይሰራል (የCLI ቶከን ዱካ፣ loopback ብቻ)
- [ ] `curl http://localhost:20128/api/shutdown` 401 ይመልሳል (ሁልጊዜ የተጠበቀ መስመር)
- [ ] `curl -H "host: evil.com" http://localhost:20128/api/mcp/sse` 401 ይመልሳል (የloopback ጥበቃ)
- [ ] የSQLite runtime በመጀመሪያው አሂድ ወደ `bundled` ይፈታል (የታሸገው ባይነሪ ለመድረኩ ትክክለኛ ነው)
- [ ] `node_modules/better-sqlite3` ሲሰረዝ የSQLite runtime ወደ `runtime` ይመለሳል
- [ ] ብልህ የMCP ማጣሪያ እውነተኛ `playwright-mcp browser_snapshot` ውጤትን ይጨምቃል (≥50% ቅነሳ)
- [ ] ሁሉም 10 `skills/omniroute*/SKILL.md` ፋይሎች በጥሬ GitHub URL በይፋ ሊደረስባቸው ይችላል
- [ ] የመጀመሪያ ማዋቀሪያ አዋቂው በአዲስ ማዋቀር ላይ "እንዴት እንደሚሰራ" የደረጃ ጉብኝት ደረጃን ያሳያል
- [ ] የመነሻ ዳሽቦርድ የደረጃ ሽፋን መግብር የተዋቀሩ/ንቁ ብዛቶችን ያሳያል

---

## ወደ ቀድሞው ስሪት መመለስ

የተለቀቀው ስሪት ወሳኝ ችግር ካለበት፦

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` ላይ አስቸኳይ ማስተካከያ → የማስተካከያ ልቀት `vX.Y.(Z+1)`
4. ወዲያውኑ በGitHub Discussions እና Discord ላይ ያሳውቁ

## ጥብቅ ደንቦች

- በቀጥታ ወደ `main` ፈጽሞ commit አታድርጉ
- በ`main` ወይም `release/*` branches ላይ `git push --force`ን ፈጽሞ አይጠቀሙ
- የHusky hooks (`--no-verify`) ፈጽሞ አይዝለሉ
- ሚስጥሮችን፣ የመግቢያ ማረጋገጫዎችን ወይም `.env` filesን ፈጽሞ commit አታድርጉ
- የሙከራ ሽፋን ≥60/60/60/60 (መግለጫዎች/መስመሮች/ፈንክሽኖች/ቅርንጫፎች) ሆኖ መቆየት አለበት
- በ`src/`፣ `open-sse/`፣ `electron/` ወይም `bin/` ውስጥ ያለውን የምርት ኮድ ሲቀይሩ ሁልጊዜ ሙከራዎችን ያካትቱ ወይም ያዘምኑ

## ራስ-ሰር የማመሳሰል ምርመራ

PR ከመክፈትዎ በፊት የሰነዶች ማመሳሰል መከላከያውን በአካባቢዎ ያስኪዱ፦

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

CIም ይህን ምርመራ በ`.github/workflows/ci.yml` (lint job) ውስጥ ያስኬዳል።