# Release Checklist (Hausa)

🌐 **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) · 🇮🇱 [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)

---

> **Sabuntawa ta ƙarshe:** 2026-08-28 — v3.8.51
> Sauƙaƙaƙƙen tsarin fitarwa wanda ke amfani da ƙwarewar Claude Code don sarrafa aiki ta atomatik.
>
> **Kiyaye layin jira/reshe cikin yanayi mai kyau tsakanin fitowa:** duba [RELEASE_GREEN.md](./RELEASE_GREEN.md)
> (dangin `/green-prs` + `npm run check:release-green` + `/babysit` + aikin dare). Gudanar da
> wannan lokaci-lokaci — musamman kuma **kafin** wannan jerin dubawa — yana sa PR ɗin fitowa ya fara cikin yanayi mai kyau.

## A taƙaice

```bash
# 1. Ɗaga sigar + samar da CHANGELOG (ƙwarewa)
/version-bump-cc patch    # ko minor/major

# 2. Gudanar da ƙofar inganci a cikin na'ura
npm run check              # lint + gwaje-gwaje
npm run test:coverage      # cikakkiyar ƙofar ɗaukar gwaji (60/60/60/60)

# 3. Gina & gwajin hayaƙi
npm run build
npm run test:e2e           # na zaɓi ne amma ana ba da shawara

# 4. Samar da fitowa (ƙwarewa)
/generate-release-cc

# 5. Tura zuwa amfani (ƙwarewa)
/deploy-vps-both-cc        # ko akamai-cc / local-cc

# 6. Ɗauki shaidun fitowa (ƙwarewa)
/capture-release-evidences-cc
```

## npm Trusted Publishing (tsoho tun daga v3.8.51) — ana yin staging idan an nema, kai tsaye a matsayin mafita ta madadin

`npm-publish.yml` yana wallafawa ta hanyar **npm Trusted Publishing (OIDC)** a matsayin tsoho: aikin
`stage-npm` (wanda GitHub ke masaukinsa) yana musanya id-token na GitHub da shaidar npm
mai ɗan gajeren wa'adi don wannan gudanarwar — babu token na npm mai dogon wa'adi a cikin sirrukan ma'ajiyar, babu buƙatar 2FA, kuma ana haɗa bayanin asali.
Wannan shi ne hanyar tsallakewa da npm ke amincewa da ita yanzu da ake daina amfani da tokens masu kauce wa 2FA;
yana dawo da cikakken tsarin atomatik da aikin yake da shi har zuwa v3.8.48 tare da kiyaye
garantin WS1.3 (token da ya fallasa ba zai iya wallafawa shi kaɗai ba — babu token).

**Saitin sau ɗaya kawai (mai shi):** npmjs.com → package `omniroute` → Settings → _Trusted
Publisher_ → GitHub: owner `diegosouzapw`, repo `OmniRoute`, workflow `npm-publish.yml`
(environment: babu). Har sai an samar da wannan, matakin atomatik zai gaza da `ENEEDAUTH`:
sake ƙaddamarwa da `publish_mode=staged` (a ƙasa) ko `direct`.

### Wallafawa ta staging (idan an nema — `publish_mode=staged`)

Tsarin aikin npm-publish ba ya ƙara wallafawa kai tsaye: yana kunna tarball ɗin da aka shirya
(`check:pack-boot`) sannan ya gudanar da `npm stage publish` — ana ajiye ainihin bytes ɗin a
registry, kuma **ba za a iya girka su ba** har sai mai shi ya amince. An matsar da ƙofar 2FA
ta ɗan Adam zuwa BAYAN tabbatarwa, ba kafin ta ba.

**Tsarin mai shi bayan workflow ya zama kore:**

1. `npm stage list omniroute` — nemo stage id (ana kuma buga shi a taƙaitaccen bayanin workflow).
2. Tabbatar da bytes da aka yi staging ɗinsu (ana ba da shawara): `npm stage download <id>`, sannan girka
   tarball da aka sauke cikin prefix na wucin gadi kuma kunna shi (`npm run check:pack-boot` yana sarrafa
   irin wannan hukuncin pack→install→boot ta atomatik a CI).
3. `npm stage approve <id>` — buƙatar 2FA ITA CE wallafawar. `npm stage reject <id>` yana watsarwa.
4. Kariyar bayan wallafawa: mai tabbatarwa bayan wallafawa (WS1.4 na shirin v3.8.49) yana girka
   sigar da aka wallafa daga registry na jama'a cikin container mai tsabta sannan ya kunna ta.

**Mafita ta gaggawa:** `workflow_dispatch` tare da `publish_mode=direct` yana dawo da
tsohon `npm publish` na gaggawa (yi amfani da shi kawai idan staging da kansa ya yi matsala; rubuta dalili).

**Ƙarfafawa na sau ɗaya kawai (mai shi, npmjs.com):** saita Trusted Publisher don
`omniroute` a yanayin stage-only domin kada token mai dogon wa'adi da ya fallasa ya iya yin `npm publish`
kai tsaye daga ko'ina — CI zai iya yin staging kawai; 2FA na mai shi kaɗai ne ke fitarwa.

**Jagorar magance artifact da ya lalace (ba a canza ba):** `npm deprecate omniroute@<bad> "<reason> — use <fixed>"`
a matsayin matakin farko na yau da kullum (mintuna, ana iya maidowa); `npm unpublish` kawai a cikin taga na awa 72/babu masu-dogaro
kuma kada ya taɓa zama matakin farko. Docker: kada a sake rubuta alamar siga — rollback yana nufin
sake nuna `latest` zuwa digest mai kyau na ƙarshe.

**Docker Hub `latest` (wajibi ne ga kowane wallafar tsayayyen SemVer):** dole ne
workflow na `docker-publish` ya sanya alama ga **duka** `X.Y.Z` da kuma, idan
`should-promote-latest.sh` ya tabbatar wannan shi ne SemVer mafi girma kuma tsayayye, `:latest`
tare da **digest iri ɗaya**. Bayan aikin: digest na Hub `latest` ya yi daidai da sabon
digest na SemVer kuma `last_updated` ya sabunta. Kada a bar `:latest` a kan tsohon
build alhali bayanan fitowa suna magana game da gyare-gyaren da ke kan git kawai. Hanyoyin farawa cikin sauri na Compose
suna amfani da `:latest`; ya kamata GitOps ya ci gaba da ɗaurewa zuwa `X.Y.Z`. Duba
[Tashoshin fitarwa na Docker](../guides/DOCKER_GUIDE.md#release-channels) da #10317.

## Hanyar Gaggawa ta Hotfix (lakabi `hotfix`)

PR mai lakabin `hotfix` yana tsallake babban tsarin gwaje-gwajen CI (E2E mai kashi 9, coverage ratchet,
quality-gate, quality-extended) kuma yana riƙe da matakan tantancewa masu sauri kuma masu ƙarfi: build,
sassan unit, integration, vitest, lint/typecheck, docs-sync, `check:pack-artifact`
da gwajin fara aiki na tarball (`check:pack-boot`). Manufa: samun koren sakamako cikin ≤15min maimakon ~33min.

**Ka'idar shiga — dole ne duka huɗun su cika (an tsara bisa hanyoyin gaggawa na Chromium/VS Code/Node):**

1. **Muniwar matsala**: production ya lalace — artifact da aka wallafa yana faɗuwa yayin fara aiki / gyaran
   tsaro / matsalar ta shafi kowane mai amfani da release ɗin. "Mai muhimmanci" ba yana nufin "ya lalace" ba.
2. **Iko**: mai repository ne kawai ke sanya lakabin `hotfix`. Lakabin SHI NE
   amincewar — kada a taɓa sanya shi da kai a campaign PR.
3. **Shaida**: jikin PR yana haɗa hanyar zuwa cikakken babban gwajin baya da ya yi kore (suite ɗin da
   jobs ɗin da aka tsallake za su sake tabbatarwa) tare da gwajin gyaran da da farko ya gaza sannan ya yi nasara.
4. **Iyaka**: cherry-pick kawai — mafi ƙarancin gyara, babu refactors, babu ƙarin canje-canje marasa alaƙa.

Za a sake tabbatar da ɓangaren coverage/ratchet da aka tsallake a cikakken gwaji na gaba a
reshe na release (ci gaba da tabbatar da release mai kore) — hanyar tana tsallake JIRA kawai, ba tabbatarwa ba.
Canje-canjen da suka shafi tests kawai (duk fayiloli suna ƙarƙashin `tests/`, babu ko ɗaya ƙarƙashin `tests/e2e/`) suna tsallake tsarin E2E
ta atomatik, ba tare da wani lakabi ba.

## Cikakken Jerin Dubawa

### Kafin Release

- [ ] An haɗa duk PRs da aka nufa don wannan release zuwa `release/vX.Y.0`
- [ ] An rufe duk buɗaɗɗun abubuwan Linear/issue na wannan version ko an tura su zuwa milestone na gaba
- [ ] CI ya yi kore a reshen `release/vX.Y.0`
- [ ] Babu alamomin `TODO(release)` a cikin code: `grep -r "TODO(release)" src/ open-sse/`
- [ ] Docker base image ya kasance na zamani (a halin yanzu `node:24.15.0-trixie-slim`)

### Version da Changelog

- [ ] Gudanar da `/version-bump-cc <patch|minor|major>` (ƙwarewar Claude Code)
  - Yana ɗaga versions na `package.json`, `electron/package.json`
  - Yana sake samar da `CHANGELOG.md` daga git commits tun daga tag na ƙarshe
  - Yana sabunta badges na README.md
- [ ] Yi bitar CHANGELOG.md da hannu kuma a gyara commit messages idan ya cancanta
- [ ] Tabbatar cewa sabon sashen semver a cikin `CHANGELOG.md` ya yi daidai da version na `package.json`
- [ ] Bar `## [Unreleased]` a matsayin sashen farko na changelog don aikin da ke tafe
- [ ] Sabunta `docs/openapi.yaml` → dole `info.version` ya yi daidai da version na `package.json`

### Ingancin Code

- [ ] `npm run lint` — errors 0 (warnings sun riga sun kasance)
- [ ] `npm run typecheck:core` — babu matsala
- [ ] `npm run typecheck:noimplicit:core` — babu matsala (strict)
- [ ] `npm run check:cycles` — babu circular deps
- [ ] `npm run check:any-budget:t11` — yana cikin budget
- [ ] `npm run check:route-validation:t06` — babu matsala
- [ ] `npm run check:node-runtime` — an cika mafi ƙarancin runtime da ake tallafawa (`>=22.22.2 <23`, `>=24.0.0 <27`, bisa `SUPPORTED_NODE_RANGE` a cikin `src/shared/utils/nodeRuntimeSupport.ts`; ya yi daidai da `engines` na `package.json`)

### Gwaje-gwaje

- [ ] `npm run test:unit` — ya wuce
- [ ] `npm run test:vitest` — ya wuce (MCP server, autoCombo, cache)
- [ ] `npm run test:coverage` — an cika ƙa'idar 60/60/60/60 (statements/lines/functions/branches)
- [ ] `npm run test:integration` — ya wuce (idan canje-canje sun shafi DB / handlers)
- [ ] `npm run test:combo:matrix` — ya wuce (combo strategy matrix: yana tabbatar da shawarwarin zaɓi na duk dabarun routing 19 na jama'a ta hanya mai maimaituwa; a gudanar idan an taɓa combo routing, strategy resolution, ko fallback logic)
- [ ] `RUN_COMBO_LIVE=1 npm run test:combo:live` — **na zaɓi/da hannu** (gwajin smoke na real-upstream mai ƙuntatawa; yana samo snapshot na DB mai karantawa kawai daga VPS `root@192.168.0.15`; yana tuntuɓar providers na gaske, yana kashe credits; ba ya taɓa gudana a CI; yana tsallakewa cikin tsabta idan babu gate)
- [ ] `npm run test:combo:live:vps` — **na zaɓi/da hannu** (gwajin smoke na VPS kai-tsaye na Phase-3: yanayin HTTP guda 7 a kan sabar `.15` mai aiki ta plain Node ESM; yana buƙatar `ssh root@192.168.0.15`; yana ƙirƙira/goge combos masu `__live_test__*` kawai; yana tuntuɓar providers na gaske; ba ya taɓa gudana a CI)
- [ ] `npm run test:e2e` — ya wuce (canje-canjen UI)
- [ ] `npm run test:protocols:e2e` — ya wuce (canje-canjen MCP/A2A)
- [ ] `npm run test:ecosystem` — ya wuce

### Hooks (Husky ya tabbatar)

Husky hooks suna cikin `.husky/` kuma suna gudana ta atomatik yayin git operations.

- **pre-commit:** `npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11`
- **pre-push:** matakan tantancewa masu sauri kuma masu sakamako iri ɗaya — `npm run check:any-budget:t11 && npm run check:tracked-artifacts` (an kunna 2026-06-13). Da gangan ba ya haɗa `test:unit` (yana da jinkiri; CI job na `test-unit` yana rufe shi).
  - Gudanar da `npm run test:unit` da hannu kafin tura release branches.

Idan hook ya gaza: gyara ainihin matsalar, kada a tsallake shi da `--no-verify`.

### Conventional Commits

Duk commits da za su shiga release dole ne su bi tsarin `type(scope): subject`.

**Valid types:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `style`, `ci`

**Valid 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`

Canje-canje masu karya jituwa: ƙara footer na `BREAKING CHANGE:` ko `!` bayan scope (misali `feat(api)!: drop /v0`).

### Takardu

- [ ] `npm run check:docs-sync` ya yi nasara (pre-commit ne ke gudanar da shi ta atomatik)
- [ ] `npm run check:docs-all` ya yi nasara (mai tattarawa: docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links)
- [ ] `npm run check:env-doc-sync` ya fita da 0 — yarjejeniyar env tsakanin lamba ↔ `.env.example` ↔ `docs/reference/ENVIRONMENT.md` tana nan daram
- [ ] `npm run check:doc-links` ya fita da 0 — babu lalatattun manazartun markdown na ciki bayan sake tsara tsarin
- [ ] An duba `docs/architecture/ARCHITECTURE.md` don karkacewar ma'ajiya/runtime
- [ ] An duba `docs/guides/TROUBLESHOOTING.md` don karkacewar env var da ayyukan gudanarwa
- [ ] Idan `.env.example` ya canza: an sabunta `docs/reference/ENVIRONMENT.md`
- [ ] Idan sabon fasali yana da UI: `docs/guides/USER_GUIDE.md` ya ambace shi
- [ ] Idan sabon fasali yana da API: an sabunta `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml`
- [ ] Idan sabon fasali module ne: akwai keɓaɓɓen `docs/<MODULE>.md`
- [ ] Idan canjin mai karya dacewa ne: `docs/guides/TROUBLESHOOTING.md` yana da bayanin ƙaura

### i18n

- [ ] `npm run i18n:check` ya fita da 0 — yanayin fassara (`.i18n-state.json`) yana daidaita da takardun tushe (babu tushe masu karkacewa a strict mode; gargaɗin warn-mode abin karɓa ne don gyare-gyaren takardu na ƙarshe, amma ya kamata ya zama 0 kafin sanya tag)
- [ ] `npm run i18n:check-ui-coverage` ya fita da 0 — kowane locale na UI yana kan ko sama da mafi ƙarancin ɗaukar hoto na 80%
- [ ] `npm run i18n:sync-ui:dry` ya bayar da rahoton maɓallan da suka ɓace 0 a dukkan locale 42
- [ ] Idan takardun tushe na Turanci sun canza, gudanar da `npm run i18n:run` (yana buƙatar `OMNIROUTE_TRANSLATION_API_KEY` a cikin `.env`) kafin sanya tag
- [ ] Ana iya ɗage gudummawar fassara zuwa sakin gaba idan ƙanana ne (a bi diddigi a CHANGELOG)

### Ƙaurawar Database

- [ ] Idan `src/lib/db/migrations/` yana da sabbin fayiloli:
  - [ ] Kowace ƙaura idempotent ce (`CREATE TABLE IF NOT EXISTS`, da sauransu)
  - [ ] An naɗe ƙaurar cikin transactions
  - [ ] An yi musu lambobi daidai (babu giɓi a jerin)
- [ ] Gwada a sabon shigarwa: goge `~/.omniroute/omniroute.db` sannan gudanar da `npm run dev`
- [ ] Gwada a shigarwar da take akwai: yi ajiyar DB, gudanar da ƙaura, tabbatar da schema
- [ ] An sarrafa fayilolin WAL (`-wal`, `-shm`) daidai idan ƙaura ta sake rubuta tables

### Katalogin Provider (Zod-validated)

- [ ] Schema na Zod a `src/shared/constants/providers.ts` yana aiki a lokacin load
  - [ ] Duk providers suna da fields da ake buƙata (`id`, `label`, `kind`, da sauransu)
  - [ ] An samar da `freeNote` ga sabbin providers na kyauta
  - [ ] Providers na OAuth suna da `oauthConfig` da aka yi wa rajista a `src/lib/oauth/constants/oauth.ts`
- [ ] Idan an ƙara sabon provider: akwai executor mai dacewa a `open-sse/executors/`
- [ ] Idan tsarin ba na OpenAI ba ne: akwai translator a `open-sse/translator/`
- [ ] An yi wa models rajista a `open-sse/config/providerRegistry.ts`
- [ ] Unit tests a `tests/unit/` sun rufe rarraba provider da routing

### Desktop (Electron)

Idan `electron/` ya canza:

- [ ] `npm run electron:smoke:packaged` ya yi nasara
- [ ] An gwada builds na aƙalla ɗaya daga cikin `:win`, `:mac`, `:linux`
- [ ] Takardun shaidar sanya hannu kan lamba ba su ƙare ba (idan ana sanya hannu)
- [ ] Version na `electron/package.json` ya yi daidai da na tushen `package.json`
- [ ] An sabunta channel pointer na auto-update idan ana fitarwa zuwa `stable`

### Tsarin Build

Repository ɗin yana amfani da output directories guda uku mabambanta — kada a taɓa gauraya su:

| Directory | Manufa                                                                 | Ana bibiyarsa?   |
| --------- | ---------------------------------------------------------------------- | ---------------- |
| `src/`    | Tushen application (TypeScript / TSX)                                  | E                |
| `.build/` | Matsakaitan build — output na `next build` (`distDir`)                 | A'a (gitignored) |
| `dist/`   | npm bundle mai shirye don aikawa — `assembleStandalone` ne ya haɗa shi | A'a (gitignored) |

> **Bayanin mai gudanarwa:** directory na image na VPS mai nisa har yanzu yana nan a `/usr/lib/node_modules/omniroute/app/`.
> Output na build na **cikin-repo** ne kawai ya matsa (`app/` → `dist/`). Skills na deploy suna yin rsync
> na abubuwan da ke cikin `dist/` zuwa dir na `app/` mai nisa — ba a buƙatar canza path na VPS.

**Gudanarwar build guda ɗaya:**

```
npm run build:release
  └─ rm -rf .build dist          (tsaftacewa)
  └─ next build → .build/next/   (matsakaita)
  └─ assembleStandalone          (yana kwafe standalone + static + public + natives → dist/)
  └─ yana rubuta dist/BUILD_SHA  (alamar tsaro ta HEAD)
```

KADA KA gudanar da `npm run build` sannan wani `npm run build:cli` daban don deploy — yi amfani da
`npm run build:release` wanda ke yin cikakken rebuild mai tsabta + alamar tsaro a umarni guda.

### Tabbatar da Artifact

- [ ] `npm run build:release` ya yi nasara kuma `dist/BUILD_SHA` == `git rev-parse --short HEAD`
- [ ] `npm run check:pack-artifact` yana da tsabta — babu `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, ko wasu ragowar gida
- [ ] `dist/server.js` yana nan bayan build
- [ ] Gwajin smoke na packaged-runtime na gida na zaɓi: `npm run dev:candidate -- validate` bayan `npm run dev:candidate -- build` yana kunna packed tarball a keɓantaccen `DATA_DIR` kuma yana duba `/api/health` + `/v1/models` (duba [Hanyar Zinariya ta Gudummawa](CONTRIBUTION_GOLDEN_PATH.md#local-candidate-loop))

### Sanya Tag & Saki

- [ ] Gudanar da `/generate-release-cc` (Claude Code skill):
  - Yana ƙirƙirar tag `vX.Y.Z`
  - Yana tura tag da branch
  - Yana buɗe GitHub Release tare da bayanin changelog
  - Yana haɗa installers na Electron (idan an gina su)
- [ ] Ko da hannu:
  ```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

Skills na deploy suna amfani da tsarin rsync mai sauƙi — babu `npm pack`, babu `npm i -g`:

- [ ] Yi amfani da ƙwarewar deploy da ta dace da wurin da ake nufi:
  - `/deploy-vps-local-cc` — VPS na gida (192.168.0.15)
  - `/deploy-vps-akamai-cc` — Akamai VPS (69.164.221.35)
  - `/deploy-vps-both-cc` — dukansu
- [ ] Kafin yin deploy, tabbatar `dist/BUILD_SHA` == `git rev-parse --short HEAD`
- [ ] Dole ne a gudanar da build a inda `node_modules` yake na ainihi (babban checkout ko worktree da aka yi wa `npm ci` — BA worktree mai symlink ba)
- [ ] Yi smoke test ga instance da aka yi wa deploy:
  - Buɗe `/dashboard/health` → duba cewa string ɗin version ya dace da release
  - Gudanar da buƙatar `/v1/chat/completions` a kan sanannen provider
  - Tabbatar `/api/monitoring/health` yana dawo da circuit breakers masu matsayin `CLOSED`
  - Tabbatar MCP transports suna amsawa (`/mcp` HTTP, `/mcp-sse` SSE)

### Bayan release

- [ ] Gudanar da `/capture-release-evidences-cc` (ƙwarewar Claude Code)
  - Yana ɗaukar hotunan allo/rikodin WebP na sabbin fasaloli
  - Yana haɗa su da bayanan release / rubutun blog
- [ ] Sabunta GitHub Discussions / Discord da sanarwar release
- [ ] Buɗe milestone don version na gaba
- [ ] Idan yana da matuƙar muhimmanci: liƙa discussion a sama ko wallafa a `news.json` don banner na cikin manhaja

### Ƙofar ƙaddamar da Radar ga jama'a

An commit da sanarwar Radar da gangan tare da `active: false`. Kunna ta wani canji ne na daban
bayan an gabatar da shaida ga kowane abu da ke ƙasa:

- [ ] An merge duk stacked Radar PRs kuma CI na release-tip yana kore
- [ ] Yi deploy da smoke test ga hanyoyin OSS Radar yayin da `RADAR_ENABLED` har yanzu yake a kashe ta tsohuwa
- [ ] Yi smoke test ga `GET /planos`, `/termos`, `/privacidade`, da `/reembolso` a kan Radar host da aka ambata
- [ ] Yi rikodin shaidar mai gudanarwa/lambar tuntuɓa/adireshi da bita ta doka da mai shi ya amince da ita a cikin private service
- [ ] Gwada Stripe Checkout da signed webhook a test mode kawai
- [ ] Gwada isar da transactional email guda ɗaya da aka rufaffen bayanansa ta amfani da sender/domain da aka amince da shi
- [ ] Tabbatar da maido da backup da research run guda ɗaya da aka sa ido a kai kuma aka kayyade kasafin kuɗinsa
- [ ] Amince da manufar bita ta BRL/PIX kafin karɓar shaidar gudummawa
- [ ] Kunna Checkout na jama'a ne kawai bayan an cika ƙofofin da suka gabata, sannan kunna sabon ID na `news.json`
- [ ] Tabbatar banner na Home yana amfani da rubutu da aka keɓance ga yare kuma sabon ID yana sake bayyana bayan an yi watsi da tsohon ID

## Gwajin smoke na Sabis da Aka Girkawa (v3.8.4+)

Kafin fitar da kowace siga da ta ƙunshi sauye-sauyen sabis da aka girka, tabbatar da waɗannan:

### Farawa da Sabuwar DB (yana gano karo tsakanin migrations — an ƙara bayan hotfix na v3.8.4)

- [ ] `DATA_DIR=$(mktemp -d) npm start &` — jira sakan 10 don ya fara
- [ ] `curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool'` yana dawo da `"9router"` (BA 404 BA, BA 500 BA). Wannan yana tabbatar da cewa an yi amfani da migration `071_services.sql` kuma an shigar da row na farko.
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(version_manager);" | grep -E "provider_expose|logs_buffer_path|last_sync_at"` yana dawo da rows 3.
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(webhooks);" | grep -E "kind|metadata_encrypted"` yana dawo da rows 2 (yana tabbatar da cewa an yi amfani da `070_webhooks_kind_metadata.sql`).
- [ ] `node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts` yana wucewa — yana karewa daga karo a nan gaba.

### 9Router

- [ ] `POST /api/services/9router/install` yana dawo da 200 tare da `installedVersion` cikin ƙasa da mintuna 2
- [ ] `POST /api/services/9router/start` yana dawo da 200 da `state: "running"` cikin ƙasa da sakan 30
- [ ] `GET /api/services/9router/status` yana nuna `health: "healthy"`
- [ ] `POST /v1/chat/completions` tare da `"model": "9router/auto/..."` yana dawo da 200 (routing daga farko zuwa ƙarshe ta cikin 9Router)
- [ ] `GET /dashboard/providers/services/9router/embed/dashboard` yana nuna UI na asali na 9Router a cikin proxy (ba iframe na kai-tsaye na `127.0.0.1:port` ba)
- [ ] `POST /api/services/9router/rotate-key` yana dawo da `{ keyRotated: true }` kuma sabis ɗin yana sake farawa ba tare da matsala ba
- [ ] `POST /api/services/9router/stop` yana dawo da 200 da `state: "stopped"`
- [ ] `GET /api/services/9router/logs?tail=50` yana dawo da rafin SSE mai event na `snapshot` wanda ke ɗauke da layukan kwanan nan
- [ ] Girkawa a muhalli da babu `npm` a PATH yana dawo da 500 tare da saƙon kuskure mai sauƙin fahimta (ba stack trace ba)

### CLIProxyAPI

- [ ] `POST /api/services/cliproxy/install` yana dawo da 200 cikin ƙasa da mintuna 2
- [ ] `POST /api/services/cliproxy/start` yana dawo da 200 da `state: "running"` cikin ƙasa da sakan 30
- [ ] `GET /api/services/cliproxy/status` yana nuna `health: "healthy"`
- [ ] `POST /api/services/cliproxy/stop` yana dawo da 200 da `state: "stopped"`
- [ ] `GET /api/services/cliproxy/logs?tail=50` yana dawo da rafin SSE

### Koma-bayan tsaro

- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/9router/start` yana dawo da `403 LOCAL_ONLY`
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/cliproxy/start` yana dawo da `403 LOCAL_ONLY`
- [ ] Amsoshin kuskure daga `/api/services/*` ba sa ƙunsar `err.stack` ko cikakkun file paths

## Binciken v3.8.0+

Kafin fitar da kowace siga ta v3.8.x, tabbatar da waɗannan ƙarin abubuwa:

- [ ] `omniroute --tray` yana farawa a macOS (an girka systray2 cikin `~/.omniroute/runtime/`)
- [ ] `omniroute --tray` yana farawa a Linux (yana buƙatar DISPLAY; yana nuna kuskure cikin tsari idan ba a saita shi ba)
- [ ] `omniroute --tray` yana farawa a Windows (PowerShell NotifyIcon, babu ƙarin binaries)
- [ ] `omniroute config tray enable` yana ƙirƙirar shigarwar autostart; disable yana cire ta
- [ ] `npm install -g omniroute@<this-version>` yana gudanar da postinstall ba tare da fatal exit ba
- [ ] Hanyar sabuntawa tana riƙe optional deps: `omniroute update --apply` da auto-updater
      suna gudanar da `npm install -g … --include=optional` domin `optionalDependencies` (better-sqlite3,
      keytar, tls-client, da tarin llmlingua SLM: `@atjsh/llmlingua-2@2.0.5`,
      `js-tiktoken`) su tsira bayan sabuntawa. Matakin ultra `modelPath` SLM yana kuma buƙatar
      tinybert model, wanda ake sauke shi ta atomatik zuwa `${DATA_DIR}/models/llmlingua` a farkon amfani. Daga nan postinstall
      (`scripts/build/colocateOptionals.mjs`) yana haɗa optional closure na SLM cikin
      `dist/node_modules` domin worker ya yi amfani da instance GUDA ƊAYA na `@huggingface/transformers` ^4.2.0
      — standalone trace yana haɗa transformers kawai, ba optionals da ake dynamic import ba,
      saboda haka idan babu wannan worker zai loda llmlingua-2 da transformers na root
      kuma matakin SLM zai kasa a ɓoye ta hanyar fail-open.
- [ ] `omniroute status` yana aiki ba tare da `.env` ba (hanyar token ta CLI, loopback kawai)
- [ ] `curl http://localhost:20128/api/shutdown` yana dawo da 401 (route da ake karewa koyaushe)
- [ ] `curl -H "host: evil.com" http://localhost:20128/api/mcp/sse` yana dawo da 401 (kariyar loopback)
- [ ] SQLite runtime yana komawa `bundled` a farkon gudanarwa (bundled binary yana aiki a kan platform ɗin)
- [ ] SQLite runtime yana komawa `runtime` idan an goge `node_modules/better-sqlite3`
- [ ] Smart MCP filter yana matse ainihin output na `playwright-mcp browser_snapshot` (raguwar ≥50%)
- [ ] Dukkan fayilolin `skills/omniroute*/SKILL.md` guda 10 ana iya samunsu a fili ta raw GitHub URL
- [ ] Onboarding wizard yana nuna matakin yawon shakatawa na tier mai suna "Yadda Yake Aiki" a sabon setup
- [ ] Widget na tier coverage a home dashboard yana nuna adadin da aka saita/masu aiki

---

## Yankewar 3.9.0 LTS (an yi atisaye a 3.8.58)

Bayan v3.8.59, sigar da za ta biyo baya ita ce 3.9.0, kuma ƙarshenta zai zama rassa biyu masu ɗorewa:
`stable/v3` (layin v3 LTS, npm `latest`) da `develop` (v4, an ɗaga zuwa 4.0.0, npm
`nightly`). Tsarin reshe/tasha, forward-port da lakabobi suna cikin
[RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md); shirin yana cikin [ROADMAP](../../ROADMAP.md) (Mataki na 3). Za a yi yankewar sau ɗaya;
3.8.58 yana yin atisayensa daga farko har ƙarshe a kan fork, sannan 3.8.59 ya rufe da
[jerin binciken GO/NO-GO](./LTS_GO_NO_GO.md).

### Gwajin bushewa (karantawa kawai, amintacce a kowane lokaci)

```bash
npm run release:dry-run-lts-cut                       # ainihin yankewar: 3.9.0 daga HEAD, alamar da ta gabata v3.8.59
npm run release:dry-run-lts-cut -- --from <3.9.0-tip> # ƙayyade commit ɗin tushe
```

`scripts/release/dry-run-lts-cut.mjs` ba ya aiwatar da komai: yana karanta git da `gh` sannan ya buga
dukkan jerin matakan — sharuɗɗan farko (an warware tushe, ma'ajiyar tushe tana da cikakken tarihi —
shallow clone ba zai iya tura `stable/v3` ba, ɓangaren karɓa yana ƙin pack a parent na farko
da aka graft, saboda haka yi yankewar daga cikakken clone ko fara da `git fetch --unshallow origin` — alamar da ta gabata
tana nan, `package.json` yana kan sigar da ake nufi, akwai buɗaɗɗen issue na `release-freeze`, babu buɗaɗɗen
issue na `Release branch not green`
a kan reshen saki da yake akwai — reshen da babu shi yana bayar da rahoton `?` wanda ba a sani ba, ba ya taɓa zama
green — an saita layin jiran Mergify na `release` (G11: `queue_rules`, `checks_timeout`,
lakabin `queue`), ruleset na `release/*` har yanzu yana hana gogewa da force-push, kuma
`stable/v3` da `develop` ba su wanzu ba tukuna), matakan reshe guda biyu, abubuwan kunna dormant-workflow
da sharuɗɗan `if:` da za su zama gaskiya (da waɗanda za su ci gaba da kasancewa a kulle ta hanyar repository variable ko
aka ɗaure su ga canonical repository), dist-tags da ake tsammani (`latest` → 3.9.0, `next` da
`nightly` babu komai) da rollback. Exit `0` = `RESULT: READY`, `1` = wani sharadin farko mai hana aiki
ya gaza (`✗`), `2` = kuskuren amfani. `--advisory <id,...>` yana sauya bincike zuwa gargaɗi (`!`)
ba tare da ɓoye shi ba.

Gudanar da gwajin bushewa na ainihin yankewar yayin da release freeze na 3.9.0 yake a buɗe — ana
ƙirƙirar rassan bayan alamar kuma kafin Mataki na 12c ya ɗage freeze ɗin.

### Atisayen 3.8.58 (a fork kawai)

```bash
# 1. Yi gwajin bushewa a kan ƙarshen yanzu tare da sigogin atisaye
npm run release:dry-run-lts-cut -- --target-version 3.8.58 --previous-tag v3.8.57 \
  --advisory freeze,base-green

# 2. Aiwatar a kan remote na FORK (ana ƙin origin, ko duk wani remote da URL ɗinsa yake na canonical
#    repository; kowane mataki yana neman tabbaci a 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. Gwada dormant workflows a cikin fork (workflow_dispatch inda gwajin bushewa
#    ya bayar da rahoton canonical-repository pin), sannan yi rollback
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
```

Ana gina develop bump commit da git plumbing (ba a taɓa working tree ba), kuma yana ɗaga
fayiloli biyar iri ɗaya da cycle-open commit: `package.json`, `open-sse/package.json`,
`electron/package.json`, `package-lock.json` da `docs/openapi.yaml`. Daga baya ana buɗe sashen
CHANGELOG na `[4.0.0]` da kwafinsa na i18n a kan `develop`, kafin PR ɗinsa na farko.
Script ɗin ba ya taɓa canza npm dist-tags — yi atisayen waɗannan a kan scratch package.

### Artifact na samfotin PR (gina sau ɗaya, tallata bytes iri ɗaya)

`.github/workflows/preview-artifact.yml` yana gina production tarball guda ɗaya daga head na PR kuma
yana inganta ainihin build ɗin nan (#8084 sashe (a)). PR na repository iri ɗaya kawai; ba a wallafa komai.

```bash
gh workflow run preview-artifact.yml -f pr_number=<N>   # ko ƙara lakabin `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                          # shigarwar samfoti
```

Gudanarwar tana yin `npm ci`, `npm run build:release`, `npm run check:pack-artifact`, tana shirya
tarball, tana gudanar da `npm run check:pack-boot` (fake secrets, ephemeral data dir), tana sake shiryawa kuma
ta gaza sai idan digest ɗin ya kasance iri ɗaya, sannan ta rubuta `artifact-identity.json` (head SHA, base
SHA, lockfile hash, platform, arch, node ABI, bundler, build policy —
`scripts/release/artifact-identity.mjs`) kuma ta tabbatar da tarball ɗin a wani job na daban. Tallata
samfoti yana nufin shigar da wannan tarball ɗin: kada a sake ginawa daga tushe.

### Yankewar (3.9.0, bayan GO)

1. An rubuta GO a cikin [LTS_GO_NO_GO.md](./LTS_GO_NO_GO.md).
2. `npm run release:dry-run-lts-cut -- --from v3.9.0` yana buga `RESULT: READY`.
3. Ƙirƙiri rassan a kan `origin` da hannu ta amfani da umarnin da gwajin bushewa ya buga —
   script ɗin ya ƙi turawa zuwa `origin`. Don sake amfani da develop commit da aka yi wa bita, gudanar da
   atisayen `--execute` a kan ƙarshen 3.9.0 a kan fork ɗinka da farko; yana buga SHA guda biyu, kuma
   ana iya tura commits iri ɗaya:

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

4. Kare `stable/v3` da `develop` (rulesets + merge queue) kafin a haɗa PR na farko.
5. Workflows ɗin da ba sa aiki za su kunna ne idan branch ya wanzu: `forward-port.yml` (push zuwa
   `stable/v3`), `validate-stable-pr.yml` (PRs zuwa `stable/v3`) da `nightly-v4-build.yml`
   (yana gina `develop`). Kafin fara aiki, saita sirrin ma’ajiyar `secrets.FORWARD_PORT_TOKEN` (domin CI ya yi aiki a kan
   PRs na forward-port); wallafawar nightly za ta ci gaba da kasancewa a kashe har sai mai ma’ajiyar ya saita
   repository variable `vars.NIGHTLY_PUBLISH` zuwa `true` kuma npm Trusted Publishing ya amince da
   `nightly-v4-build.yml`. Ana tantance channel ta `scripts/release/dist-tag.mjs`, wato resolver ɗin da
   `npm-publish.yml` yake amfani da shi.
6. Tabbatar da channels: `npm view omniroute dist-tags --json` ya nuna `latest` = 3.9.0 kuma babu
   `next` / `nightly` har sai an wallafa v4.
7. Komawa baya, idan ya zama dole: `git push origin --delete refs/heads/stable/v3 refs/heads/develop`
   da `npm dist-tag add omniroute@3.8.59 latest`.

---

## Mayar da Sigar Baya

Idan sakin yana da matsala mai tsanani:

1. `gh release edit vX.Y.Z --prerelease` (yana nuna cewa ba shi ne na baya-bayan nan ba)
2. `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z` (kawai idan masu amfani ba su fara amfani da shi ba tukuna)
3. Ko: gyaran gaggawa a kan `release/vX.Y.0` → sakin gyara `vX.Y.(Z+1)`
4. A sanar nan take a GitHub Discussions da Discord

## Ƙa'idoji Masu Tsauri

- Kada a taɓa yin commit kai tsaye zuwa `main`
- Kada a taɓa amfani da `git push --force` zuwa rassan `main` ko `release/*`
- Kada a taɓa tsallake Husky hooks (`--no-verify`)
- Kada a taɓa yin commit na sirrika, bayanan shiga, ko fayilolin `.env`
- Dole ne coverage ya kasance ≥60/60/60/60 (statements/lines/functions/branches)
- Koyaushe a haɗa ko a sabunta gwaje-gwaje yayin sauya lambar samarwa a cikin `src/`, `open-sse/`, `electron/`, ko `bin/`

## Binciken Daidaitawa Na Atomatik

Gudanar da kariyar daidaita takardu a na'urarka kafin buɗe PR:

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

CI ma yana gudanar da wannan binciken a cikin `.github/workflows/ci.yml` (aikin lint).