Two files, one repository

diegosouzapw/OmniRoute ships 4 formats across 6 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ CLAUDE.md AGENTS.md ↔ GEMINI.md AGENTS.md ↔ Copilot instructions CLAUDE.md ↔ GEMINI.md CLAUDE.md ↔ Copilot instructions GEMINI.md ↔ Copilot instructions

A · CLAUDE.md · 5651 words B · .github/copilot-instructions.md · 170 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	40	1	0%
Commands	1	39	0	3%
Section tags	4	9	1	29%

What each file covers

Sections

0 shared · 40 only in A · 1 only in B

− CLAUDE.md
− Quick Start
− Running Tests
− Single test file (Node.js native test runner — most tests)
− Vitest (MCP server, autoCombo, cache)
− All suites
− Project at a Glance
− Request Pipeline
− Resilience Runtime State
− Provider Circuit Breaker
− Connection Cooldown
− Model Lockout
− Debugging Guidance
− Key Conventions
− Code Style
− Database
− Error Handling
− Security
− Common Modification Scenarios
− Adding a New Provider
− Adding a New API Route
− Adding a New DB Module
− Adding a New MCP Tool
− Adding a New A2A Skill
− Adding a New Cloud Agent
− Adding a New Embedded Service
− Adding a New Guardrail / Eval / Skill / Webhook event
− Reference Documentation
− Testing
− Planning & Research Artifacts (superpowers, deep-research)
− Git Workflow
− Never commit directly to main
− Worktree isolation (MANDATORY for every development task)
− Environment
− Quality Gates & Ratchets
− Hard Rules
− PII & Stream Sanitization Learnings
− 1. Regex Security (ReDoS)
− 2. SSE Snapshot Handling
− 3. Database Handles in Tests
+ OmniRoute PR and Coverage Instructions

Commands

1 shared · 39 only in A · 0 only in B

− npm install
− npm run dev
− npm run build
− npm run lint
− npm run typecheck:core
− npm run typecheck:noimplicit:core
− npm run check
− npm run check:cycles
− node --import tsx/esm --test tests/unit/your-file.test.ts
− npm run test:vitest
− npm run test:all
− git checkout -b feat/your-feature
− git commit -m "feat: describe your change"
− git push -u origin feat/your-feature
− git fetch origin "$BASE_BRANCH"
− git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"
− npm run test:unit
− node --import tsx/esm --test tests/unit/file.test.ts
− npm run test:e2e
− npm run test:protocols:e2e
− npm run test:ecosystem
− npm run coverage:report
− git -C _tasks …
− docker
− git checkout
− git worktree remove .claude/worktrees/<dir>
− git branch -D <task>
− node:test
− bun:sqlite
− bun install -g omniroute
− npm ci
− node --import tsx
− bun
− bun: not found
− npm run quality:ratchet -- --update
− node
− gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open
− gh pr edit <N> --base release/vX+1
− gh pr view <N> --json baseRefName
npm run test:coverage

Section tags

4 shared · 9 only in A · 1 only in B

− setup
− build
− lint-format
− security
− database
− api
− deployment
− do-not
− docs
+ testing-strategy
test
code-style
git-pr
agent-behaviour

Line diff

+14 added−571 removed2 unchanged0.4% identical

diegosouzapw/OmniRoute · CLAUDE.md

@@ −1 @@

1# CLAUDE.md

3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

5## Quick Start

7```bash

8npm install # Install deps (auto-generates .env from .env.example)

9npm run dev # Dev server at http://localhost:20128

10npm run build # Production build (Next.js 16 standalone)

11npm run lint # ESLint (0 errors expected; warnings are pre-existing)

12npm run typecheck:core # TypeScript check (should be clean)

13npm run typecheck:noimplicit:core # Strict check (no implicit any)

14npm run test:coverage # Unit tests + coverage gate (60/60/60/60 — statements/lines/functions/branches)

15npm run check # lint + test combined

16npm run check:cycles # Detect circular dependencies

17```

19### Running Tests

21```bash

22# Single test file (Node.js native test runner — most tests)

23node --import tsx/esm --test tests/unit/your-file.test.ts

25# Vitest (MCP server, autoCombo, cache)

26npm run test:vitest

28# All suites

29npm run test:all

30```

32For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep architecture, see `AGENTS.md`.

34---

36## Project at a Glance

38**OmniRoute** — unified AI proxy/router. One endpoint, 290 LLM providers, auto-fallback.

40| Layer | Location | Purpose |

41| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |

42| API Routes | `src/app/api/v1/` | Next.js App Router — entry points |

43| Handlers | `open-sse/handlers/` | Request processing (chat, embeddings, etc) |

44| Executors | `open-sse/executors/` | Provider-specific HTTP dispatch |

45| Translators | `open-sse/translator/` | Format conversion (OpenAI↔Claude↔Gemini) |

46| Transformer | `open-sse/transformer/` | Responses API ↔ Chat Completions |

47| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc |

48| Database | `src/lib/db/` | SQLite domain modules (130 migrations) |

49| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic |

50| MCP Server | `open-sse/mcp-server/` | 104 tools (42 base + memory/skill/agentSkill/pool/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 31 scopes |

51| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol |

52| Skills | `src/lib/skills/` | Extensible skill framework |

53| Memory | `src/lib/memory/` | Persistent conversational memory |

55Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point).

57---

59## Request Pipeline

61```

62Client → /v1/chat/completions (Next.js route)

63 → CORS → Zod validation → auth? → policy check → prompt injection guard

64 → handleChatCore() [open-sse/handlers/chatCore.ts]

65 → cache check → rate limit → combo routing?

66 → resolveComboTargets() → handleSingleModel() per target

67 → translateRequest() → getExecutor() → executor.execute()

68 → fetch() upstream → retry w/ backoff

69 → response translation → SSE stream or JSON

70 → If Responses API: responsesTransformer.ts TransformStream

71```

73API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific.

75**Combo routing** (`open-sse/services/combo.ts`): 19 public strategies (priority, weighted, fill-first, round-robin, p2c, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, cache-optimized, context-relay, fusion, pipeline). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. The `fusion` strategy is the exception: it fans out to a panel of models in parallel, then a judge model synthesizes one final answer (`open-sse/services/fusion.ts`). See `docs/routing/AUTO-COMBO.md` for the 13-factor Auto-Combo scoring + the full strategy table and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers.

77---

79## Resilience Runtime State

81OmniRoute has three related but distinct temporary-failure mechanisms. Keep their

82scope separate when debugging routing behavior. See the

83[3-layer resilience diagram](./docs/diagrams/exported/resilience-3layers.svg)

84(source: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))

85for an at-a-glance map.

87### Provider Circuit Breaker

89**Scope**: whole provider, e.g. `glm`, `openai`, `anthropic`.

91**Purpose**: stop sending traffic to a provider that is repeatedly failing at the

92upstream/service level, so one unhealthy provider does not slow down every request.

94**Implementation**:

96- Core class: `src/shared/utils/circuitBreaker.ts`

97- Chat gate/execution wiring: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`

98- Runtime status API: `src/app/api/monitoring/health/route.ts`

99- Shared wrappers: `open-sse/services/accountFallback.ts`

100- Persisted state table: `domain_circuit_breakers`

101

102**States**:

103

104- `CLOSED`: normal traffic is allowed.

105- `OPEN`: provider is temporarily blocked; callers get a provider-circuit-open response

106 or combo routing skips to another target.

107- `HALF_OPEN`: reset timeout has elapsed; allow a probe request. Success closes the

108 breaker, failure opens it again.

109

110**Defaults** (`open-sse/config/constants.ts`):

111

112- OAuth providers: threshold `3`, reset timeout `60s`.

113- API-key providers: threshold `5`, reset timeout `30s`.

114- Local providers: threshold `2`, reset timeout `15s`.

115

116Only provider-level failure statuses should trip the provider breaker:

117

118```ts

119(408, 500, 502, 503, 504);

120```

121

122Do not trip the whole-provider breaker for normal account/key/model errors like most

123`401`, `403`, or `429` cases. Those usually belong to connection cooldown or model

124lockout. A generic API-key provider `403` should be recoverable unless it is classified

125as a terminal provider/account error.

126

127The breaker uses lazy recovery, not a background timer. When `OPEN` expires, reads such

128as `getStatus()`, `canExecute()`, and `getRetryAfterMs()` refresh the state to

129`HALF_OPEN`, so dashboards and combo candidate builders do not keep excluding an

130expired provider forever.

131

132### Connection Cooldown

133

134**Scope**: one provider connection/account/key.

135

136**Purpose**: temporarily skip one bad key/account while allowing other connections for

137the same provider to continue serving requests.

138

139**Implementation**:

140

141- Write/update path: `src/sse/services/auth.ts::markAccountUnavailable()`

142- Account selection/filtering: `src/sse/services/auth.ts::getProviderCredentials...`

143- Cooldown calculation: `open-sse/services/accountFallback.ts::checkFallbackError()`

144- Settings: `src/lib/resilience/settings.ts`

145

146Important fields on provider connections:

147

148```ts

149rateLimitedUntil;

150testStatus: "unavailable";

151lastError;

152lastErrorType;

153errorCode;

154backoffLevel;

155```

156

157During account selection, a connection is skipped while:

158

159```ts

160new Date(rateLimitedUntil).getTime() > Date.now();

161```

162

163Cooldowns are also lazy: when `rateLimitedUntil` is in the past, the connection becomes

164eligible again. On successful use, `clearAccountError()` clears `testStatus`,

165`rateLimitedUntil`, error fields, and `backoffLevel`.

166

167Default connection cooldown behavior:

168

169- OAuth base cooldown: `5s`.

170- API-key base cooldown: `3s`.

171- API-key `429` should prefer upstream retry hints (`Retry-After`, reset headers, or

172 parseable reset text) when available.

173- Repeated recoverable failures use exponential backoff:

174

175```ts

176baseCooldownMs * 2 ** failureIndex;

177```

178

179The anti-thundering-herd guard prevents concurrent failures on the same connection from

180repeatedly extending the cooldown or double-incrementing `backoffLevel`.

181

182Terminal states are not cooldowns. `banned`, `expired`, and `credits_exhausted` are

183intended to stay unavailable until credentials/settings change or an operator resets

184them. Do not overwrite terminal states with transient cooldown state.

185

186### Model Lockout

187

188**Scope**: provider + connection + model.

189

190**Purpose**: avoid disabling a whole connection when only one model is unavailable or

191quota-limited for that connection.

192

193Examples:

194

195- Per-model quota providers returning `429`.

196- Local providers returning `404` for one missing model.

197- Provider-specific mode/model permission failures such as selected Grok modes.

198

199Model lockout lives in `open-sse/services/accountFallback.ts` and lets the same

200connection continue serving other models.

201

202### Debugging Guidance

203

204- If all keys for a provider are skipped, inspect both provider breaker state and each

205 connection's `rateLimitedUntil`/`testStatus`.

206- If a provider appears permanently excluded after the reset window, check whether code

207 is reading raw `state` instead of using `getStatus()`/`canExecute()`.

208- If one provider key fails but others should work, prefer connection cooldown over

209 provider breaker.

210- If only one model fails, prefer model lockout over connection cooldown.

211- If a state should self-recover, it should have a future timestamp/reset timeout and a

212 read path that refreshes expired state. Permanent statuses require manual credential

213 or config changes.

214

215---

216

217## Key Conventions

218

219### Code Style

220

221- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas (enforced by lint-staged via Prettier)

222- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative

223- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE

224- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = error everywhere; `no-explicit-any` = **error** in `open-sse/` and `tests/` (since #6218 — pre-existing violations are frozen in `config/quality/eslint-suppressions.json`, new ones must be fixed; `npm run lint` applies the suppressions and is what CI runs)

225- **TypeScript**: `strict: false`, target ES2022, module esnext, resolution bundler. Prefer explicit types.

226

227### Database

228

229- **Always** go through `src/lib/db/` domain modules — **never** write raw SQL in routes or handlers

230- **Never** add logic to `src/lib/localDb.ts` (re-export layer only)

231- **Never** barrel-import from `localDb.ts` — import specific `db/` modules instead

232- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling)

233- Migrations: `src/lib/db/migrations/` — versioned SQL files, idempotent, run in transactions

234

235### Error Handling

236

237- try/catch with specific error types, log with pino context

238- Never swallow errors in SSE streams — use abort signals for cleanup

239- Return proper HTTP status codes (4xx/5xx)

240

241### Security

242

243- **Never** use `eval()`, `new Function()`, or implied eval

244- Validate all inputs with Zod schemas

245- Encrypt credentials at rest (AES-256-GCM)

246- Upstream header denylist: `src/shared/constants/upstreamHeaders.ts` — keep sanitize, Zod schemas, and unit tests aligned when editing

247- **Public upstream credentials** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys extracted from public CLIs): **MUST** be embedded via `resolvePublicCred()` from `open-sse/utils/publicCreds.ts` — **never** as string literals. See `docs/security/PUBLIC_CREDS.md` for the mandatory pattern.

248- **Error responses** (HTTP / SSE / executor / MCP handler): **MUST** route through `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts` — **never** put raw `err.stack` or `err.message` in a response body. See `docs/security/ERROR_SANITIZATION.md`.

249- **Shell commands built from variables**: when calling `exec()`/`spawn()` with a script that needs runtime values, pass them via the `env` option (shell-escaped automatically) — **never** string-interpolate untrusted/external paths into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.

250- **Secure-by-default libraries** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): prefer Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink over custom implementations whenever adding new security-sensitive surfaces.

251

252---

253

254## Common Modification Scenarios

255

256### Adding a New Provider

257

2581. Register in `src/shared/constants/providers.ts` (Zod-validated at load)

2592. Add executor in `open-sse/executors/` if custom logic needed (extend `BaseExecutor`)

2603. Add translator in `open-sse/translator/` if non-OpenAI format

2614. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based — if the upstream CLI ships a public client_id/secret, embed via `resolvePublicCred()` (see `docs/security/PUBLIC_CREDS.md`), **never** as a literal

2625. Register models in `open-sse/config/providerRegistry.ts`

2636. Write tests in `tests/unit/` (include the publicCreds shape assertion if you added a new embedded default)

264

265### Adding a New API Route

266

2671. Create directory under `src/app/api/v1/your-route/`

2682. Create `route.ts` with `GET`/`POST` handlers

2693. Follow pattern: CORS → Zod body validation → optional auth → handler delegation

2704. Handler goes in `open-sse/handlers/` (import from there, not inline)

2715. Error responses use `buildErrorBody()` / `errorResponse()` from `open-sse/utils/error.ts` (auto-sanitized — never put `err.stack` or `err.message` raw in the body). See `docs/security/ERROR_SANITIZATION.md`.

2726. Add tests — including at least one assertion that error responses do not leak stack traces (`!body.error.message.includes("at /")`)

273

274### Adding a New DB Module

275

2761. Create `src/lib/db/yourModule.ts` — import `getDbInstance` from `./core.ts`

2772. Export CRUD functions for your domain table(s)

2783. Add migration in `src/lib/db/migrations/` if new tables needed

2794. Re-export from `src/lib/localDb.ts` (add to the re-export list only)

2805. Write tests

281

282### Adding a New MCP Tool

283

2841. Add tool definition in `open-sse/mcp-server/tools/` with Zod input schema + async handler

2852. Register in tool set (wired by `createMcpServer()`)

2863. Assign to appropriate scope(s)

2874. Write tests (tool invocation logged to `mcp_audit` table)

288

289### Adding a New A2A Skill

290

2911. Create skill in `src/lib/a2a/skills/` (5 already exist: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)

2922. Skill receives task context (messages, metadata) → returns structured result

2933. Register in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts`

2944. Expose in `src/app/.well-known/agent.json/route.ts` (Agent Card)

2955. Write tests in `tests/unit/`

2966. Document in `docs/frameworks/A2A-SERVER.md` skill table

297

298### Adding a New Cloud Agent

299

3001. Create agent class in `src/lib/cloudAgent/agents/` extending `CloudAgentBase` (3 already exist: codex-cloud, devin, jules)

3012. Implement `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`

3023. Register in `src/lib/cloudAgent/registry.ts`

3034. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`)

3045. Tests + document in `docs/frameworks/CLOUD_AGENT.md`

305

306### Adding a New Embedded Service

307

3081. Create installer in `src/lib/services/installers/{name}.ts` modeled on `ninerouter.ts` (use `runNpm` from `installers/utils.ts` — no shell interpolation, hard rule #13).

3092. Register the service in `src/lib/services/bootstrap.ts` (add to `SERVICES[]` array and extend `buildSpawnArgsFactory()`).

3103. Add a DB seed row for the new service in `src/lib/db/migrations/` (`version_manager` table, `status='not_installed'`, `auto_start=0`).

3114. Create 7 API endpoints under `src/app/api/services/{name}/` (`_lib.ts`, `install`, `start`, `stop`, `restart`, `update`, `status`, `auto-start`). All delegate errors through `createErrorResponse()`. The shared `logs` endpoint is already wired via `[name]/logs/route.ts`.

3125. Verify `/api/services/` is in `LOCAL_ONLY_API_PREFIXES` in `src/server/authz/routeGuard.ts`; add a test asserting `isLocalOnlyPath()` returns `true` for the new prefix if you add one (hard rule #17).

3136. Add a UI tab in `src/app/(dashboard)/dashboard/providers/services/tabs/` reusing `ServiceStatusCard`, `ServiceLifecycleButtons`, `ServiceLogsPanel`.

3147. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/openapi.yaml`.

3158. Write tests: unit (`tests/unit/services/`), integration (`tests/integration/services/`, gated by `RUN_SERVICES_INT=1`), and update `docs/ops/RELEASE_CHECKLIST.md` smoke section.

316

317### Adding a New Guardrail / Eval / Skill / Webhook event

318

319- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md`

320- Eval suite: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md`

321- Skill (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md`

322- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md`

323

324---

325

326## Reference Documentation

327

328For any non-trivial change, read the matching deep-dive first:

329

330| Area | Doc |

331| --------------------------------------------- | ------------------------------------------------------- |

332| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` |

333| Architecture | `docs/architecture/ARCHITECTURE.md` |

334| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |

335| Auto-Combo (13-factor scoring, 19 strategies) | `docs/routing/AUTO-COMBO.md` |

336| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` |

337| Reasoning replay | `docs/routing/REASONING_REPLAY.md` |

338| Skills framework | `docs/frameworks/SKILLS.md` |

339| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` |

340| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` |

341| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` |

342| Public upstream credentials (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` |

343| Error message sanitization | `docs/security/ERROR_SANITIZATION.md` |

344| Evals | `docs/frameworks/EVALS.md` |

345| Compliance / audit | `docs/security/COMPLIANCE.md` |

346| Webhooks | `docs/frameworks/WEBHOOKS.md` |

347| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` |

348| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` |

349| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |

350| MCP server | `docs/frameworks/MCP-SERVER.md` |

351| A2A server | `docs/frameworks/A2A-SERVER.md` |

352| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` |

353| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` |

354| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |

355| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` |

356| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md` |

357

358---

359

360## Testing

361

362| What | Command |

363| ----------------------- | --------------------------------------------------------------------------- |

364| Unit tests | `npm run test:unit` |

365| Single file | `node --import tsx/esm --test tests/unit/file.test.ts` |

366| Vitest (MCP, autoCombo) | `npm run test:vitest` |

367| E2E (Playwright) | `npm run test:e2e` |

368| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` |

369| Ecosystem | `npm run test:ecosystem` |

370| Coverage gate | `npm run test:coverage` (60/60/60/60 — statements/lines/functions/branches) |

371| Coverage report | `npm run coverage:report` |

372

373**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`, you must include or update tests in the same PR.

374

375**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.

376

377**Both test runners must pass**: `npm run test:unit` (Node native — most tests) AND `npm run test:vitest` (MCP server, autoCombo, cache) cover **non-overlapping files**. Both are wired in CI (jobs `test-unit` and `test-vitest`) and must be green before merging. A PR where only one suite passes may silently ship broken MCP tools or routing regressions.

378

379**Bug fix / issue triage protocol (Hard Rule #18)**: Every fix for a reported issue must be validated by one of the following — no exceptions:

380

3811. **TDD (preferred)** — write a failing test reproducing the bug → fix it → confirm the test passes. The test becomes the permanent regression guard. Touch only the files the test proves need changing; nothing more.

3822. **Real-environment test (when TDD is not possible)** — deploy to the production VPS (`root@192.168.0.15`) and run a documented live test. Record the exact command + result in the PR description. Applies to: OAuth upstream flows, Cloudflare/WS upstream behavior, UI-only regressions, hardware-dependent behavior.

3833. "It worked locally without a test" does not count. A fix without a test or a VPS validation record is not a fix — it is a guess.

384

385Why this matters: fixing bug A while opening bug B is worse than not fixing at all. The TDD/VPS gate enforces surgical scope — you touch only what the failing test proves is broken. Examples where this paid off: #3090 (claude-web 403), #3113 (WS HTTP fallback), #3052 (heap-guard auto-calibration).

386

387**Copilot coverage policy**: When a PR changes production code and coverage is below 60% (statements/lines/functions/branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.

388

389---

390

391## Planning & Research Artifacts (superpowers, deep-research)

392

393`_tasks/` is a **separate, isolated git repository** that is gitignored by the main

394repo (`.gitignore` → `_tasks/`). It is the canonical home for working artifacts —

395plans, specs/designs, research, hand-offs — so they stay **versioned in their own

396repo** instead of polluting the main OmniRoute tree.

397

398**Hard rule — never write superpowers / planning / research output under `docs/` or

399the repo root.** The superpowers skills ship with defaults that point at `docs/…`

400(`writing-plans` → `docs/superpowers/plans/`, `brainstorming` → `docs/superpowers/specs/`).

401Those defaults are **overridden here**. Whenever you invoke superpowers (or any

402plan/spec/research generator) in this project, save to `_tasks/` instead, using the

403same filename convention:

404

405| Artifact (skill) | Default (do NOT use) | Save here instead |

406| ---------------------------------- | ------------------------- | ------------------------------------------------------------- |

407| Plans (`writing-plans`) | `docs/superpowers/plans/` | `_tasks/superpowers/plans/YYYY-MM-DD-<feature>.md` |

408| Specs / design (`brainstorming`) | `docs/superpowers/specs/` | `_tasks/superpowers/specs/YYYY-MM-DD-<topic>-design.md` |

409| Research (`deep-research`, ad-hoc) | `docs/research/` | `_tasks/research/…` |

410| Hand-offs (`/handoff`) | — | `_tasks/hands-off/<YYYY-MM-DD>_<branch>_v<versão>_sess-<id>/` |

411

412When a superpowers skill announces a path like "saved to `docs/superpowers/plans/…`",

413rewrite it to the `_tasks/…` equivalent before writing. Commit those artifacts inside

414the `_tasks/` repo (`git -C _tasks …`), never in the main repo.

415

416## Git Workflow

417

418```bash

419# Never commit directly to main

420git checkout -b feat/your-feature

421git commit -m "feat: describe your change"

422git push -u origin feat/your-feature

423```

424

425**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

426

427**Commit format** (Conventional Commits): `feat(db): add circuit breaker` — scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

428

429**Husky hooks**:

430

431- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` + `check:tracked-artifacts`

432- **pre-push**: intentionally light (PATH/npm sanity only). `any-budget` + `tracked-artifacts`

433 already run on pre-commit; re-running them on every push was pure double-pay. CI still

434 enforces both. (Was Fase 6A.12 full pre-push gate; folded into pre-commit in #6716.)

435

436### Worktree isolation (MANDATORY for every development task)

437

438Multiple sessions/agents work this repo in parallel. The main checkout is **shared**, so a

439`git checkout`/branch switch in it silently discards another session's uncommitted work and

440yanks the branch out from under whatever else is running (incidents: 2026-06-05, 2026-06-13).

441

442**Rule: never develop on the shared main checkout. Every task gets its own git worktree on its

443own dedicated branch, and you MUST confirm the base branch with the operator before creating it.**

444

4451. **Ask first — which base branch?** Before creating anything, ask the operator (via

446 `AskUserQuestion`, unless they already told you) from which branch the new worktree/branch

447 should be cut. Do NOT assume `main` or "whatever I'm on" — the answer is usually the active

448 `release/vX.Y.Z`, but it can be another feature/release branch. Get the base explicitly.

4492. **Create an isolated worktree + branch off that base** (never reuse the main checkout).

450 **🔴 MANDATORY PATH: every worktree lives under `.claude/worktrees/` — and nowhere else.**

451 This is the single canonical location (the same dir the native `EnterWorktree` tool uses). It

452 is gitignored AND in the `tsconfig.json` / `.dockerignore` excludes, so worktrees never leak

453 into the build scope. **Never** use `.worktrees/`, repo-root, or any other path — a worktree

454 outside `.claude/worktrees/` (a) escapes the build-scope excludes and poisons `next build` (the

455 `tsconfig` `include: **/*` globs ~70× the codebase → OOM; incident 2026-06-25) and (b) scatters

456 worktrees across two dirs.

457

458 ```bash

459 BASE_BRANCH="release/vX.Y.Z" # ← the branch the operator confirmed in step 1

460 TASK="feat/your-feature" # feat/ fix/ refactor/ docs/ test/ chore/

461 git fetch origin "$BASE_BRANCH"

462 git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"

463 cd ".claude/worktrees/${TASK##*/}"

464 # Reuse the main checkout's node_modules to skip a per-worktree npm install.

465 # HARD LINKS (`cp -al`), never a symlink: ~5s for the whole tree and near-zero extra

466 # disk (the inodes are shared), and unlike a symlink it does not break the dev server.

467 cp -al "$(git -C <main_checkout> rev-parse --show-toplevel)/node_modules" node_modules

468 ```

469

470 **Never `ln -s` node_modules.** Turbopack rejects a symlink that resolves outside the

471 project root, so `npm run dev` dies with a FATAL panic (`Symlink [project]/node_modules

472 is invalid, it points out of the filesystem root`) while typecheck, lint and the test

473 runners all keep passing — the error names "filesystem root", not the worktree, so it

474 reads like a Next/build bug and costs real time to trace (incident 2026-07-31, #9043).

475

476 In Claude Code prefer the native `EnterWorktree` tool (it already creates worktrees under

477 `.claude/worktrees/`): create the worktree with the command above, then call `EnterWorktree`

478 with its `path`.

479

4803. **Work, commit, push, open the PR — all from inside the worktree.** Never `git checkout` a

481 different branch inside a worktree another session might share.

4824. **Tear down only your own** worktree + branch when done, from the main checkout:

483 `git worktree remove .claude/worktrees/<dir>` then `git branch -D <task>`. Never blanket-delete

484 `fix/*`/`feat/*` — other sessions keep their own; delete only the branches you created, by name.

4855. **Never touch another session's worktree, branch, or uncommitted changes.** If `git worktree

486list` shows worktrees you didn't create, leave them alone. End every session with the main

487 checkout back on the branch it started on (the active `release/vX.Y.Z`, never `main`).

488

489---

490

491## Environment

492

493- **Runtime**: Node.js ≥22.0.0 <23 || ≥24.0.0 <27, ES Modules. This is the **only supported** runtime for the published `omniroute` CLI, the server, and the test suites (`node:test` + vitest) — `engines.node` is authoritative and end users never need Bun. A **best-effort `bun:sqlite` compatibility path** exists so a global Bun install (`bun install -g omniroute`) can start without `better-sqlite3` (driver adapter + Bun-aware process spawning); it is **not** a supported runtime — no support guarantees — and every Bun-specific runtime change MUST preserve the Node driver/fallback chain and ship a Bun test (`test:bun:db`) or an explicit reason why the path is Node-only.

494- **Bun (build/dev script runner + compatibility smoke only)**: Bun `1.3.14` is pinned as an **exact devDependency** (provisioned through the existing `npm ci` via the lockfile's `@oven/bun-*` platform binaries — no `setup-bun`/ad-hoc install). It is used **only** to execute a small, allow-listed set of TypeScript **gate/generator scripts** (replacing `node --import tsx` for startup speed): the CI checks `check:provider-consistency`, `check:compression-budget`, `check:known-symbols`, and the non-CI `gen:provider-reference`, `bench:compression` — plus the focused `test:bun:db` compatibility smoke suite for the best-effort `bun:sqlite` path. **Do NOT** widen Bun to `npm install`, the build (`build:cli*`), `check:pack-artifact`, the supported published runtime, or the main test runners — those stay on Node. Any new Bun-invoking gate/generator script must be validated byte-identical against its `node --import tsx` output first. After pulling the lockfile change, run `npm install` so `bun` resolves locally (a stale `node_modules` will fail those scripts with `bun: not found`).

495- **TypeScript**: 6.0+, target ES2022, module esnext, resolution bundler

496- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`

497- **Default port**: 20128 (API + dashboard on same port)

498- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`

499- **Key env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`

500- Setup: `cp .env.example .env` then generate `JWT_SECRET` (`openssl rand -base64 48`) and `API_KEY_SECRET` (`openssl rand -hex 32`)

501

502---

503

504## Quality Gates & Ratchets

505

506OmniRoute has **~48 quality-gate scripts** (`scripts/check/` + `scripts/quality/`) wired

507across **9 gate-running jobs** in `.github/workflows/ci.yml` (`lint`, `quality-gate`,

508`quality-extended`, `docs-sync-strict`, `i18n-ui-coverage`, `i18n`, `pr-test-policy`,

509`test-vitest`, `sonarqube`), plus the `quality.yml` fast-gates job (PR→`release/**`) and

5103 nightly workflows (`nightly-property`, `nightly-resilience`, `nightly-llm-security`;

511`nightly-mutation` once merged). Full inventory, per-job breakdown, and operational

512procedures are in [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md).

513

514**Quick reference:**

515

516- Gates in jobs `lint` + `docs-sync-strict`: pass/fail policy gates —

517 fix the violation or add an allowlist entry with a justification comment + tracking issue.

518- Gates in job `quality-gate`: ratchet — metrics (ESLint warnings, code coverage, duplication,

519 complexity) must not regress vs `quality-baseline.json`. Update via

520 `npm run quality:ratchet -- --update` when a metric genuinely improves.

521- Job `test-vitest` runs `npm run test:vitest` (MCP tools, autoCombo, cache) — blocking.

522 `test:vitest:ui` is advisory until UI component tests are triaged.

523

524**Allowlist policy (short form):** Fix the cause; use the allowlist only for pre-existing

525violations you cannot fix in the same PR. Add a comment with justification + issue number.

526Stale allowlist entries (suppressing a violation that no longer exists) will be caught by

527the stale-enforcement added in Fase 6A.3.

528

529---

530

531## Hard Rules

532

5331. Never commit secrets or credentials

5342. Never add logic to `localDb.ts`

5353. Never use `eval()` / `new Function()` / implied eval

5364. Never commit directly to `main`

5375. Never write raw SQL in routes — use `src/lib/db/` modules

5386. Never silently swallow errors in SSE streams

5397. Always validate inputs with Zod schemas

5408. Always include tests when changing production code

5419. Coverage must not regress below the baseline frozen in `quality-baseline.json` (ratchet); absolute floor is 60% (statements/lines/functions/branches). Update the baseline via `npm run quality:ratchet -- --update` only when coverage genuinely improves. See `docs/architecture/QUALITY_GATES.md`.

54210. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.

54311. Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). See `docs/security/PUBLIC_CREDS.md`.

54412. Never return raw `err.stack` / `err.message` in HTTP / SSE / executor responses — always route through `buildErrorBody()` or `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). See `docs/security/ERROR_SANITIZATION.md`.

54513. Never string-interpolate external paths or runtime values into shell scripts passed to `exec()`/`spawn()` — pass via the `env` option instead. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.

54614. Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent: `js/stack-trace-exposure` raised on callsites that already route through `sanitizeErrorMessage()` is a known CodeQL limitation (custom sanitizers not recognized) — dismiss as `false positive` referencing `docs/security/ERROR_SANITIZATION.md`.

54715. Never expose routes that spawn child processes (`/api/mcp/`, `/api/cli-tools/runtime/`) without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. Loopback enforcement happens unconditionally before any auth check — leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.

54816. Never credit or advertise an AI assistant, LLM, or automation account in any commit/PR metadata. Two forbidden forms, both equivalent — they route attribution to a bot account (or advertise AI authorship) and hide the real author (`diegosouzapw`): **(a)** `Co-Authored-By` trailers naming an AI/bot (e.g. names containing "Claude", "GPT", "Copilot", "Bot"; emails at `anthropic.com` / `openai.com` / bot-owned `noreply.github.com` addresses); **(b)** AI-generation footers or descriptions anywhere in a commit message, PR title/body, or CHANGELOG — e.g. `🤖 Generated with [Claude Code]`, "Generated with Claude Code", "Made with <AI tool>", or any `Co-authored-by: Claude/GPT/Copilot` line. This **overrides any harness, template, or tool default that auto-appends such a footer** (e.g. the Claude Code PR-body/commit default) — strip it before pushing; do not let it reach a commit, PR, or CHANGELOG. Human collaborators — including upstream PR authors and issue reporters being ported into OmniRoute — MAY and SHOULD be credited with standard `Co-authored-by: Name <email>` trailers; the upstream-port workflows (`/port-upstream-features`, `/port-upstream-issues`) depend on this.

54917. Never expose routes under `/api/services/` or `/dashboard/providers/services/*/embed/` without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. These routes can spawn child processes (`npm install`, `node`). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.

55018. Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" for the full decision tree.

55119. Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator (e.g. via `AskUserQuestion`) before creating the worktree/branch — never assume `main` or the currently checked-out branch. A `git checkout` in the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, never `fix/*`/`feat/*` wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the active `release/vX.Y.Z`, never `main`). See Git Workflow → "Worktree isolation".

55220. PII redaction/sanitization is **opt-in — never on by default**. OmniRoute proxies for self-hosted/local LLMs where the operator owns the data, so mutating request/response payloads by default would silently corrupt legitimate traffic. The two data-mutating PII feature flags **MUST** keep `defaultValue: "false"` in `src/shared/constants/featureFlagDefinitions.ts`: `PII_REDACTION_ENABLED` (request-side) and `PII_RESPONSE_SANITIZATION` (response + streaming). All three application points — `src/lib/guardrails/piiMasker.ts` (request guardrail), `src/lib/piiSanitizer.ts` (response), `src/lib/streamingPiiTransform.ts` (SSE) — are gated on these flags; with both off the `pii-masker` guardrail still runs but never mutates payloads (data passes through untouched). Flipping either default to `"true"` requires explicit operator approval. The regression guard is `tests/unit/pii-opt-in-default.test.ts` (asserts both definition defaults + behavioral pass-through). Opt-in is per-operator via env or the settings/DB override (`src/lib/db/featureFlags.ts`), never a silent default. See `docs/security/GUARDRAILS.md`.

55321. **Release-freeze — the FROZEN release branch belongs to the release captain; development does NOT stop (parallel-cycle model, 2026-07-04).** `/generate-release` opens a marker issue labeled `release-freeze` at the start of reconciliation (Phase 0a), **immediately cuts the next cycle's branch `release/vX+1` from the frozen tip (Phase 0a.0b — bump + living release PR + re-home of open PRs)**, and closes the freeze once the release PR squash-merges to `main`. Before merging **any** PR, every campaign workflow (`/review-prs`, `/review-group-prs`, `/merge-prs`, `/triage-fix-bugs`, `/implement-fix-bugs`, `/triage-features`, `/implement-features`, `/green-prs`, `/port-upstream-*`) **MUST** check `gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open` — if a freeze is active: **NEVER merge into the frozen `release/vX.Y.Z` named in the freeze title**; instead resolve the ACTIVE development branch (the **highest** `release/v*` by semver — normally `release/vX+1`, announced in a freeze-issue comment) and **retarget the PR there** (`gh pr edit <N> --base release/vX+1`, then VERIFY with `gh pr view <N> --json baseRefName` — the edit fails silently) and merge normally. **HOLD only when the highest release/v\* branch IS the frozen one** (the short window before 0a.0b completes, or a pre-parallel-cycle release) — in that case leave the PR ready and open, tell the operator, and resume when the next branch appears or the freeze lifts. The just-shipped fixes reach `release/vX+1` via the Phase 5 sync-back (`scripts/release/sync-next-cycle.mjs`); do not try to sync mid-release. This is a **coordination signal, not a permission lock**: the release captain and the campaign sessions share the `diegosouzapw` identity, so a GitHub branch-protection lock cannot distinguish them — only this honored marker prevents the mid-release commit races that forced full CHANGELOG re-reconciliation in v3.8.40/v3.8.41 (a parallel campaign advanced `release/vX.Y.Z` by 34 commits mid-run). The release captain's own reconciliation/cycle-open pushes are exempt — they _are_ the release. Fixes that must land during a freeze (a homologation finding) follow the post-merge read-only rule: land on `main` first via `fix/release-vX.Y.Z-*`. **⛔ ONLY `/generate-release` may raise a release-freeze, and ONLY at its Phase 0a (start of generating a new version) — lifted at Phase 12c after the squash-merge to `main`.** No campaign, session, or agent may open a `release-freeze` marker at any other time — a freeze is **never** a mid-development coordination tool. If a session ever believes a freeze is genuinely, unavoidably necessary outside the `/generate-release` flow, it **MUST first ask the operator (`diegosouzapw`) in chat, explicitly alert "estou criando um freeze" and get an explicit yes** — never open, extend, or re-open a `release-freeze` autonomously. Conversely, do **not** close/lift an active `/generate-release` freeze to unblock campaign merges: it protects the captain's single clean CI run and auto-lifts at Phase 12c — closing it early re-triggers the exact commit race it prevents. Verify a freeze is legitimate before acting on it: an open `release-freeze` whose title/body references an **OPEN** release PR (`gh pr view <N> --json state`) is the authorized captain freeze — hold, don't touch.

55422. **Cross-session safety — this repo is worked by MANY parallel sessions/agents at once; never step on another's in-flight work.** Two absolute bans, both recurring incidents (this rule exists because they keep happening):

555 - **(a) Never `git stash` / `git stash pop` — ANYWHERE in this repo, including inside an isolated worktree, and including inside any subagent you dispatch.** `git stash` operates on the **shared repository object store**, not the per-worktree working tree — so a stash pushed or popped in one session can silently clobber or resurrect another parallel session's uncommitted changes. This is not hypothetical: 2026-07-02 a `#5923` quotaCache change leaked into the unrelated `#2296` worktree via a global `stash pop`, and the same class reincided through a **subagent**. To compare working changes against a base ref **without** stashing, use `git show <ref>:<path>` or `git diff <ref> -- <path>`; to confirm a typecheck/lint error is pre-existing on the base, inspect the base ref directly (`git show origin/release/vX.Y.Z:<path>`) — never stash your tree away to "get it clean". **Put this ban verbatim in the prompt of every subagent that touches git** (agents don't inherit this file's context — the recurrence was a subagent).

556 - **(b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working.** An open PR whose head is a live fix worktree in `.claude/worktrees/` you did **not** create (e.g. `fix-5852`/`fix-5923` carrying fresh commits, even when they share your `diegosouzapw` identity), or any branch another session owns, is **off-limits — HOLD**, and let the owning session merge it. **Before** merging or pushing to any PR you did not create _this_ session, run `git worktree list` to check for a matching in-flight worktree and re-check `gh pr view <N> --json state,headRefOid`. Only the owning session merges its own in-flight PR; mid-flight merges race the owner and re-trigger the exact commit/CHANGELOG races Rule #19 and Rule #21 guard against. (Reinforces Rule #19.)

557

558---

559

560## PII & Stream Sanitization Learnings

561

562### 1. Regex Security (ReDoS)

563

564All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges `{1,7}`) to prevent catastrophic backtracking when processing untrusted inputs.

565

566### 2. SSE Snapshot Handling

567

568When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (`done` or `completed` events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream.

569

570### 3. Database Handles in Tests

571

572Ensure that any unit tests that trigger database migrations or establish SQLite connections call `resetDbInstance()` and properly clean up/close all DB handles in a `test.after(...)` hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely.

573

diegosouzapw/OmniRoute · .github/copilot-instructions.md

@@ +1 @@

1# OmniRoute PR and Coverage Instructions

3- Treat `npm run test:coverage` as a required gate for PR work.

4- The repository minimum is `60%` for statements, lines, functions, and branches.

5- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include automated tests in the same PR.

6- When reviewing or updating a PR, if the report shows missing tests or coverage below `60%`, do not stop after reporting the problem. Add or update tests in the PR first, rerun the coverage gate, and only then ask for confirmation.

7- Prefer the smallest test layer that proves the behavior:

8 - unit tests first

9 - integration tests when multiple modules or DB state are involved

10 - e2e only when the behavior is truly UI or workflow-dependent

11- For bug issues, try to encode the reproduction as an automated test before or alongside the fix.

12- In the final PR report, include:

13 - the commands you ran

14 - the changed test files

15 - the final coverage result

@@ −1 +1 @@

1−# CLAUDE.md

1+# OmniRoute PR and Coverage Instructions

3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

4−

5−## Quick Start

6−

7−```bash

8−npm install # Install deps (auto-generates .env from .env.example)

9−npm run dev # Dev server at http://localhost:20128

10−npm run build # Production build (Next.js 16 standalone)

11−npm run lint # ESLint (0 errors expected; warnings are pre-existing)

12−npm run typecheck:core # TypeScript check (should be clean)

13−npm run typecheck:noimplicit:core # Strict check (no implicit any)

14−npm run test:coverage # Unit tests + coverage gate (60/60/60/60 — statements/lines/functions/branches)

15−npm run check # lint + test combined

16−npm run check:cycles # Detect circular dependencies

17−```

18−

19−### Running Tests

20−

21−```bash

22−# Single test file (Node.js native test runner — most tests)

23−node --import tsx/esm --test tests/unit/your-file.test.ts

24−

25−# Vitest (MCP server, autoCombo, cache)

26−npm run test:vitest

27−

28−# All suites

29−npm run test:all

30−```

31−

32−For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep architecture, see `AGENTS.md`.

33−

34−---

35−

36−## Project at a Glance

37−

38−**OmniRoute** — unified AI proxy/router. One endpoint, 290 LLM providers, auto-fallback.

39−

40−| Layer | Location | Purpose |

41−| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |

42−| API Routes | `src/app/api/v1/` | Next.js App Router — entry points |

43−| Handlers | `open-sse/handlers/` | Request processing (chat, embeddings, etc) |

44−| Executors | `open-sse/executors/` | Provider-specific HTTP dispatch |

45−| Translators | `open-sse/translator/` | Format conversion (OpenAI↔Claude↔Gemini) |

46−| Transformer | `open-sse/transformer/` | Responses API ↔ Chat Completions |

47−| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc |

48−| Database | `src/lib/db/` | SQLite domain modules (130 migrations) |

49−| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic |

50−| MCP Server | `open-sse/mcp-server/` | 104 tools (42 base + memory/skill/agentSkill/pool/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 31 scopes |

51−| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol |

52−| Skills | `src/lib/skills/` | Extensible skill framework |

53−| Memory | `src/lib/memory/` | Persistent conversational memory |

54−

55−Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point).

56−

57−---

58−

59−## Request Pipeline

60−

61−```

62−Client → /v1/chat/completions (Next.js route)

63− → CORS → Zod validation → auth? → policy check → prompt injection guard

64− → handleChatCore() [open-sse/handlers/chatCore.ts]

65− → cache check → rate limit → combo routing?

66− → resolveComboTargets() → handleSingleModel() per target

67− → translateRequest() → getExecutor() → executor.execute()

68− → fetch() upstream → retry w/ backoff

69− → response translation → SSE stream or JSON

70− → If Responses API: responsesTransformer.ts TransformStream

71−```

72−

73−API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific.

74−

75−**Combo routing** (`open-sse/services/combo.ts`): 19 public strategies (priority, weighted, fill-first, round-robin, p2c, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, cache-optimized, context-relay, fusion, pipeline). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. The `fusion` strategy is the exception: it fans out to a panel of models in parallel, then a judge model synthesizes one final answer (`open-sse/services/fusion.ts`). See `docs/routing/AUTO-COMBO.md` for the 13-factor Auto-Combo scoring + the full strategy table and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers.

76−

77−---

78−

79−## Resilience Runtime State

80−

81−OmniRoute has three related but distinct temporary-failure mechanisms. Keep their

82−scope separate when debugging routing behavior. See the

83−[3-layer resilience diagram](./docs/diagrams/exported/resilience-3layers.svg)

84−(source: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))

85−for an at-a-glance map.

86−

87−### Provider Circuit Breaker

88−

89−**Scope**: whole provider, e.g. `glm`, `openai`, `anthropic`.

90−

91−**Purpose**: stop sending traffic to a provider that is repeatedly failing at the

92−upstream/service level, so one unhealthy provider does not slow down every request.

93−

94−**Implementation**:

95−

96−- Core class: `src/shared/utils/circuitBreaker.ts`

97−- Chat gate/execution wiring: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`

98−- Runtime status API: `src/app/api/monitoring/health/route.ts`

99−- Shared wrappers: `open-sse/services/accountFallback.ts`

100−- Persisted state table: `domain_circuit_breakers`

101−

102−**States**:

103−

104−- `CLOSED`: normal traffic is allowed.

105−- `OPEN`: provider is temporarily blocked; callers get a provider-circuit-open response

106− or combo routing skips to another target.

107−- `HALF_OPEN`: reset timeout has elapsed; allow a probe request. Success closes the

108− breaker, failure opens it again.

109−

110−**Defaults** (`open-sse/config/constants.ts`):

111−

112−- OAuth providers: threshold `3`, reset timeout `60s`.

113−- API-key providers: threshold `5`, reset timeout `30s`.

114−- Local providers: threshold `2`, reset timeout `15s`.

115−

116−Only provider-level failure statuses should trip the provider breaker:

117−

118−```ts

119−(408, 500, 502, 503, 504);

120−```

121−

122−Do not trip the whole-provider breaker for normal account/key/model errors like most

123−`401`, `403`, or `429` cases. Those usually belong to connection cooldown or model

124−lockout. A generic API-key provider `403` should be recoverable unless it is classified

125−as a terminal provider/account error.

126−

127−The breaker uses lazy recovery, not a background timer. When `OPEN` expires, reads such

128−as `getStatus()`, `canExecute()`, and `getRetryAfterMs()` refresh the state to

129−`HALF_OPEN`, so dashboards and combo candidate builders do not keep excluding an

130−expired provider forever.

131−

132−### Connection Cooldown

133−

134−**Scope**: one provider connection/account/key.

135−

136−**Purpose**: temporarily skip one bad key/account while allowing other connections for

137−the same provider to continue serving requests.

138−

139−**Implementation**:

140−

141−- Write/update path: `src/sse/services/auth.ts::markAccountUnavailable()`

142−- Account selection/filtering: `src/sse/services/auth.ts::getProviderCredentials...`

143−- Cooldown calculation: `open-sse/services/accountFallback.ts::checkFallbackError()`

144−- Settings: `src/lib/resilience/settings.ts`

145−

146−Important fields on provider connections:

147−

148−```ts

149−rateLimitedUntil;

150−testStatus: "unavailable";

151−lastError;

152−lastErrorType;

153−errorCode;

154−backoffLevel;

155−```

156−

157−During account selection, a connection is skipped while:

158−

159−```ts

160−new Date(rateLimitedUntil).getTime() > Date.now();

161−```

162−

163−Cooldowns are also lazy: when `rateLimitedUntil` is in the past, the connection becomes

164−eligible again. On successful use, `clearAccountError()` clears `testStatus`,

165−`rateLimitedUntil`, error fields, and `backoffLevel`.

166−

167−Default connection cooldown behavior:

168−

169−- OAuth base cooldown: `5s`.

170−- API-key base cooldown: `3s`.

171−- API-key `429` should prefer upstream retry hints (`Retry-After`, reset headers, or

172− parseable reset text) when available.

173−- Repeated recoverable failures use exponential backoff:

174−

175−```ts

176−baseCooldownMs * 2 ** failureIndex;

177−```

178−

179−The anti-thundering-herd guard prevents concurrent failures on the same connection from

180−repeatedly extending the cooldown or double-incrementing `backoffLevel`.

181−

182−Terminal states are not cooldowns. `banned`, `expired`, and `credits_exhausted` are

183−intended to stay unavailable until credentials/settings change or an operator resets

184−them. Do not overwrite terminal states with transient cooldown state.

185−

186−### Model Lockout

187−

188−**Scope**: provider + connection + model.

189−

190−**Purpose**: avoid disabling a whole connection when only one model is unavailable or

191−quota-limited for that connection.

192−

193−Examples:

194−

195−- Per-model quota providers returning `429`.

196−- Local providers returning `404` for one missing model.

197−- Provider-specific mode/model permission failures such as selected Grok modes.

198−

199−Model lockout lives in `open-sse/services/accountFallback.ts` and lets the same

200−connection continue serving other models.

201−

202−### Debugging Guidance

203−

204−- If all keys for a provider are skipped, inspect both provider breaker state and each

205− connection's `rateLimitedUntil`/`testStatus`.

206−- If a provider appears permanently excluded after the reset window, check whether code

207− is reading raw `state` instead of using `getStatus()`/`canExecute()`.

208−- If one provider key fails but others should work, prefer connection cooldown over

209− provider breaker.

210−- If only one model fails, prefer model lockout over connection cooldown.

211−- If a state should self-recover, it should have a future timestamp/reset timeout and a

212− read path that refreshes expired state. Permanent statuses require manual credential

213− or config changes.

214−

215−---

216−

217−## Key Conventions

218−

219−### Code Style

220−

221−- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas (enforced by lint-staged via Prettier)

222−- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative

223−- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE

224−- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = error everywhere; `no-explicit-any` = **error** in `open-sse/` and `tests/` (since #6218 — pre-existing violations are frozen in `config/quality/eslint-suppressions.json`, new ones must be fixed; `npm run lint` applies the suppressions and is what CI runs)

225−- **TypeScript**: `strict: false`, target ES2022, module esnext, resolution bundler. Prefer explicit types.

226−

227−### Database

228−

229−- **Always** go through `src/lib/db/` domain modules — **never** write raw SQL in routes or handlers

230−- **Never** add logic to `src/lib/localDb.ts` (re-export layer only)

231−- **Never** barrel-import from `localDb.ts` — import specific `db/` modules instead

232−- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling)

233−- Migrations: `src/lib/db/migrations/` — versioned SQL files, idempotent, run in transactions

234−

235−### Error Handling

236−

237−- try/catch with specific error types, log with pino context

238−- Never swallow errors in SSE streams — use abort signals for cleanup

239−- Return proper HTTP status codes (4xx/5xx)

240−

241−### Security

242−

243−- **Never** use `eval()`, `new Function()`, or implied eval

244−- Validate all inputs with Zod schemas

245−- Encrypt credentials at rest (AES-256-GCM)

246−- Upstream header denylist: `src/shared/constants/upstreamHeaders.ts` — keep sanitize, Zod schemas, and unit tests aligned when editing

247−- **Public upstream credentials** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys extracted from public CLIs): **MUST** be embedded via `resolvePublicCred()` from `open-sse/utils/publicCreds.ts` — **never** as string literals. See `docs/security/PUBLIC_CREDS.md` for the mandatory pattern.

248−- **Error responses** (HTTP / SSE / executor / MCP handler): **MUST** route through `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts` — **never** put raw `err.stack` or `err.message` in a response body. See `docs/security/ERROR_SANITIZATION.md`.

249−- **Shell commands built from variables**: when calling `exec()`/`spawn()` with a script that needs runtime values, pass them via the `env` option (shell-escaped automatically) — **never** string-interpolate untrusted/external paths into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.

250−- **Secure-by-default libraries** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): prefer Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink over custom implementations whenever adding new security-sensitive surfaces.

251−

252−---

253−

254−## Common Modification Scenarios

255−

256−### Adding a New Provider

257−

258−1. Register in `src/shared/constants/providers.ts` (Zod-validated at load)

259−2. Add executor in `open-sse/executors/` if custom logic needed (extend `BaseExecutor`)

260−3. Add translator in `open-sse/translator/` if non-OpenAI format

261−4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based — if the upstream CLI ships a public client_id/secret, embed via `resolvePublicCred()` (see `docs/security/PUBLIC_CREDS.md`), **never** as a literal

262−5. Register models in `open-sse/config/providerRegistry.ts`

263−6. Write tests in `tests/unit/` (include the publicCreds shape assertion if you added a new embedded default)

264−

265−### Adding a New API Route

266−

267−1. Create directory under `src/app/api/v1/your-route/`

268−2. Create `route.ts` with `GET`/`POST` handlers

269−3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation

270−4. Handler goes in `open-sse/handlers/` (import from there, not inline)

271−5. Error responses use `buildErrorBody()` / `errorResponse()` from `open-sse/utils/error.ts` (auto-sanitized — never put `err.stack` or `err.message` raw in the body). See `docs/security/ERROR_SANITIZATION.md`.

272−6. Add tests — including at least one assertion that error responses do not leak stack traces (`!body.error.message.includes("at /")`)

273−

274−### Adding a New DB Module

275−

276−1. Create `src/lib/db/yourModule.ts` — import `getDbInstance` from `./core.ts`

277−2. Export CRUD functions for your domain table(s)

278−3. Add migration in `src/lib/db/migrations/` if new tables needed

279−4. Re-export from `src/lib/localDb.ts` (add to the re-export list only)

280−5. Write tests

281−

282−### Adding a New MCP Tool

283−

284−1. Add tool definition in `open-sse/mcp-server/tools/` with Zod input schema + async handler

285−2. Register in tool set (wired by `createMcpServer()`)

286−3. Assign to appropriate scope(s)

287−4. Write tests (tool invocation logged to `mcp_audit` table)

288−

289−### Adding a New A2A Skill

290−

291−1. Create skill in `src/lib/a2a/skills/` (5 already exist: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)

292−2. Skill receives task context (messages, metadata) → returns structured result

293−3. Register in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts`

294−4. Expose in `src/app/.well-known/agent.json/route.ts` (Agent Card)

295−5. Write tests in `tests/unit/`

296−6. Document in `docs/frameworks/A2A-SERVER.md` skill table

297−

298−### Adding a New Cloud Agent

299−

300−1. Create agent class in `src/lib/cloudAgent/agents/` extending `CloudAgentBase` (3 already exist: codex-cloud, devin, jules)

301−2. Implement `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`

302−3. Register in `src/lib/cloudAgent/registry.ts`

303−4. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`)

304−5. Tests + document in `docs/frameworks/CLOUD_AGENT.md`

305−

306−### Adding a New Embedded Service

307−

308−1. Create installer in `src/lib/services/installers/{name}.ts` modeled on `ninerouter.ts` (use `runNpm` from `installers/utils.ts` — no shell interpolation, hard rule #13).

309−2. Register the service in `src/lib/services/bootstrap.ts` (add to `SERVICES[]` array and extend `buildSpawnArgsFactory()`).

310−3. Add a DB seed row for the new service in `src/lib/db/migrations/` (`version_manager` table, `status='not_installed'`, `auto_start=0`).

311−4. Create 7 API endpoints under `src/app/api/services/{name}/` (`_lib.ts`, `install`, `start`, `stop`, `restart`, `update`, `status`, `auto-start`). All delegate errors through `createErrorResponse()`. The shared `logs` endpoint is already wired via `[name]/logs/route.ts`.

312−5. Verify `/api/services/` is in `LOCAL_ONLY_API_PREFIXES` in `src/server/authz/routeGuard.ts`; add a test asserting `isLocalOnlyPath()` returns `true` for the new prefix if you add one (hard rule #17).

313−6. Add a UI tab in `src/app/(dashboard)/dashboard/providers/services/tabs/` reusing `ServiceStatusCard`, `ServiceLifecycleButtons`, `ServiceLogsPanel`.

314−7. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/openapi.yaml`.

315−8. Write tests: unit (`tests/unit/services/`), integration (`tests/integration/services/`, gated by `RUN_SERVICES_INT=1`), and update `docs/ops/RELEASE_CHECKLIST.md` smoke section.

316−

317−### Adding a New Guardrail / Eval / Skill / Webhook event

318−

319−- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md`

320−- Eval suite: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md`

321−- Skill (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md`

322−- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md`

323−

324−---

325−

326−## Reference Documentation

327−

328−For any non-trivial change, read the matching deep-dive first:

329−

330−| Area | Doc |

331−| --------------------------------------------- | ------------------------------------------------------- |

332−| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` |

333−| Architecture | `docs/architecture/ARCHITECTURE.md` |

334−| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |

335−| Auto-Combo (13-factor scoring, 19 strategies) | `docs/routing/AUTO-COMBO.md` |

336−| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` |

337−| Reasoning replay | `docs/routing/REASONING_REPLAY.md` |

338−| Skills framework | `docs/frameworks/SKILLS.md` |

339−| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` |

340−| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` |

341−| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` |

342−| Public upstream credentials (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` |

343−| Error message sanitization | `docs/security/ERROR_SANITIZATION.md` |

344−| Evals | `docs/frameworks/EVALS.md` |

345−| Compliance / audit | `docs/security/COMPLIANCE.md` |

346−| Webhooks | `docs/frameworks/WEBHOOKS.md` |

347−| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` |

348−| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` |

349−| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |

350−| MCP server | `docs/frameworks/MCP-SERVER.md` |

351−| A2A server | `docs/frameworks/A2A-SERVER.md` |

352−| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` |

353−| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` |

354−| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |

355−| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` |

356−| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md` |

357−

358−---

359−

360−## Testing

361−

362−| What | Command |

363−| ----------------------- | --------------------------------------------------------------------------- |

364−| Unit tests | `npm run test:unit` |

365−| Single file | `node --import tsx/esm --test tests/unit/file.test.ts` |

366−| Vitest (MCP, autoCombo) | `npm run test:vitest` |

367−| E2E (Playwright) | `npm run test:e2e` |

368−| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` |

369−| Ecosystem | `npm run test:ecosystem` |

370−| Coverage gate | `npm run test:coverage` (60/60/60/60 — statements/lines/functions/branches) |

371−| Coverage report | `npm run coverage:report` |

372−

373−**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`, you must include or update tests in the same PR.

374−

375−**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.

376−

377−**Both test runners must pass**: `npm run test:unit` (Node native — most tests) AND `npm run test:vitest` (MCP server, autoCombo, cache) cover **non-overlapping files**. Both are wired in CI (jobs `test-unit` and `test-vitest`) and must be green before merging. A PR where only one suite passes may silently ship broken MCP tools or routing regressions.

378−

379−**Bug fix / issue triage protocol (Hard Rule #18)**: Every fix for a reported issue must be validated by one of the following — no exceptions:

380−

381−1. **TDD (preferred)** — write a failing test reproducing the bug → fix it → confirm the test passes. The test becomes the permanent regression guard. Touch only the files the test proves need changing; nothing more.

382−2. **Real-environment test (when TDD is not possible)** — deploy to the production VPS (`root@192.168.0.15`) and run a documented live test. Record the exact command + result in the PR description. Applies to: OAuth upstream flows, Cloudflare/WS upstream behavior, UI-only regressions, hardware-dependent behavior.

383−3. "It worked locally without a test" does not count. A fix without a test or a VPS validation record is not a fix — it is a guess.

384−

385−Why this matters: fixing bug A while opening bug B is worse than not fixing at all. The TDD/VPS gate enforces surgical scope — you touch only what the failing test proves is broken. Examples where this paid off: #3090 (claude-web 403), #3113 (WS HTTP fallback), #3052 (heap-guard auto-calibration).

386−

387−**Copilot coverage policy**: When a PR changes production code and coverage is below 60% (statements/lines/functions/branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.

388−

389−---

390−

391−## Planning & Research Artifacts (superpowers, deep-research)

392−

393−`_tasks/` is a **separate, isolated git repository** that is gitignored by the main

394−repo (`.gitignore` → `_tasks/`). It is the canonical home for working artifacts —

395−plans, specs/designs, research, hand-offs — so they stay **versioned in their own

396−repo** instead of polluting the main OmniRoute tree.

397−

398−**Hard rule — never write superpowers / planning / research output under `docs/` or

399−the repo root.** The superpowers skills ship with defaults that point at `docs/…`

400−(`writing-plans` → `docs/superpowers/plans/`, `brainstorming` → `docs/superpowers/specs/`).

401−Those defaults are **overridden here**. Whenever you invoke superpowers (or any

402−plan/spec/research generator) in this project, save to `_tasks/` instead, using the

403−same filename convention:

404−

405−| Artifact (skill) | Default (do NOT use) | Save here instead |

406−| ---------------------------------- | ------------------------- | ------------------------------------------------------------- |

407−| Plans (`writing-plans`) | `docs/superpowers/plans/` | `_tasks/superpowers/plans/YYYY-MM-DD-<feature>.md` |

408−| Specs / design (`brainstorming`) | `docs/superpowers/specs/` | `_tasks/superpowers/specs/YYYY-MM-DD-<topic>-design.md` |

409−| Research (`deep-research`, ad-hoc) | `docs/research/` | `_tasks/research/…` |

410−| Hand-offs (`/handoff`) | — | `_tasks/hands-off/<YYYY-MM-DD>_<branch>_v<versão>_sess-<id>/` |

411−

412−When a superpowers skill announces a path like "saved to `docs/superpowers/plans/…`",

413−rewrite it to the `_tasks/…` equivalent before writing. Commit those artifacts inside

414−the `_tasks/` repo (`git -C _tasks …`), never in the main repo.

415−

416−## Git Workflow

417−

418−```bash

419−# Never commit directly to main

420−git checkout -b feat/your-feature

421−git commit -m "feat: describe your change"

422−git push -u origin feat/your-feature

423−```

424−

425−**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

426−

427−**Commit format** (Conventional Commits): `feat(db): add circuit breaker` — scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

428−

429−**Husky hooks**:

430−

431−- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` + `check:tracked-artifacts`

432−- **pre-push**: intentionally light (PATH/npm sanity only). `any-budget` + `tracked-artifacts`

433− already run on pre-commit; re-running them on every push was pure double-pay. CI still

434− enforces both. (Was Fase 6A.12 full pre-push gate; folded into pre-commit in #6716.)

435−

436−### Worktree isolation (MANDATORY for every development task)

437−

438−Multiple sessions/agents work this repo in parallel. The main checkout is **shared**, so a

439−`git checkout`/branch switch in it silently discards another session's uncommitted work and

440−yanks the branch out from under whatever else is running (incidents: 2026-06-05, 2026-06-13).

441−

442−**Rule: never develop on the shared main checkout. Every task gets its own git worktree on its

443−own dedicated branch, and you MUST confirm the base branch with the operator before creating it.**

444−

445−1. **Ask first — which base branch?** Before creating anything, ask the operator (via

446− `AskUserQuestion`, unless they already told you) from which branch the new worktree/branch

447− should be cut. Do NOT assume `main` or "whatever I'm on" — the answer is usually the active

448− `release/vX.Y.Z`, but it can be another feature/release branch. Get the base explicitly.

449−2. **Create an isolated worktree + branch off that base** (never reuse the main checkout).

450− **🔴 MANDATORY PATH: every worktree lives under `.claude/worktrees/` — and nowhere else.**

451− This is the single canonical location (the same dir the native `EnterWorktree` tool uses). It

452− is gitignored AND in the `tsconfig.json` / `.dockerignore` excludes, so worktrees never leak

453− into the build scope. **Never** use `.worktrees/`, repo-root, or any other path — a worktree

454− outside `.claude/worktrees/` (a) escapes the build-scope excludes and poisons `next build` (the

455− `tsconfig` `include: **/*` globs ~70× the codebase → OOM; incident 2026-06-25) and (b) scatters

456− worktrees across two dirs.

457−

458− ```bash

459− BASE_BRANCH="release/vX.Y.Z" # ← the branch the operator confirmed in step 1

460− TASK="feat/your-feature" # feat/ fix/ refactor/ docs/ test/ chore/

461− git fetch origin "$BASE_BRANCH"

462− git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"

463− cd ".claude/worktrees/${TASK##*/}"

464− # Reuse the main checkout's node_modules to skip a per-worktree npm install.

465− # HARD LINKS (`cp -al`), never a symlink: ~5s for the whole tree and near-zero extra

466− # disk (the inodes are shared), and unlike a symlink it does not break the dev server.

467− cp -al "$(git -C <main_checkout> rev-parse --show-toplevel)/node_modules" node_modules

468− ```

469−

470− **Never `ln -s` node_modules.** Turbopack rejects a symlink that resolves outside the

471− project root, so `npm run dev` dies with a FATAL panic (`Symlink [project]/node_modules

472− is invalid, it points out of the filesystem root`) while typecheck, lint and the test

473− runners all keep passing — the error names "filesystem root", not the worktree, so it

474− reads like a Next/build bug and costs real time to trace (incident 2026-07-31, #9043).

475−

476− In Claude Code prefer the native `EnterWorktree` tool (it already creates worktrees under

477− `.claude/worktrees/`): create the worktree with the command above, then call `EnterWorktree`

478− with its `path`.

479−

480−3. **Work, commit, push, open the PR — all from inside the worktree.** Never `git checkout` a

481− different branch inside a worktree another session might share.

482−4. **Tear down only your own** worktree + branch when done, from the main checkout:

483− `git worktree remove .claude/worktrees/<dir>` then `git branch -D <task>`. Never blanket-delete

484− `fix/*`/`feat/*` — other sessions keep their own; delete only the branches you created, by name.

485−5. **Never touch another session's worktree, branch, or uncommitted changes.** If `git worktree

486−list` shows worktrees you didn't create, leave them alone. End every session with the main

487− checkout back on the branch it started on (the active `release/vX.Y.Z`, never `main`).

488−

489−---

490−

491−## Environment

492−

493−- **Runtime**: Node.js ≥22.0.0 <23 || ≥24.0.0 <27, ES Modules. This is the **only supported** runtime for the published `omniroute` CLI, the server, and the test suites (`node:test` + vitest) — `engines.node` is authoritative and end users never need Bun. A **best-effort `bun:sqlite` compatibility path** exists so a global Bun install (`bun install -g omniroute`) can start without `better-sqlite3` (driver adapter + Bun-aware process spawning); it is **not** a supported runtime — no support guarantees — and every Bun-specific runtime change MUST preserve the Node driver/fallback chain and ship a Bun test (`test:bun:db`) or an explicit reason why the path is Node-only.

494−- **Bun (build/dev script runner + compatibility smoke only)**: Bun `1.3.14` is pinned as an **exact devDependency** (provisioned through the existing `npm ci` via the lockfile's `@oven/bun-*` platform binaries — no `setup-bun`/ad-hoc install). It is used **only** to execute a small, allow-listed set of TypeScript **gate/generator scripts** (replacing `node --import tsx` for startup speed): the CI checks `check:provider-consistency`, `check:compression-budget`, `check:known-symbols`, and the non-CI `gen:provider-reference`, `bench:compression` — plus the focused `test:bun:db` compatibility smoke suite for the best-effort `bun:sqlite` path. **Do NOT** widen Bun to `npm install`, the build (`build:cli*`), `check:pack-artifact`, the supported published runtime, or the main test runners — those stay on Node. Any new Bun-invoking gate/generator script must be validated byte-identical against its `node --import tsx` output first. After pulling the lockfile change, run `npm install` so `bun` resolves locally (a stale `node_modules` will fail those scripts with `bun: not found`).

495−- **TypeScript**: 6.0+, target ES2022, module esnext, resolution bundler

496−- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`

497−- **Default port**: 20128 (API + dashboard on same port)

498−- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`

499−- **Key env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`

500−- Setup: `cp .env.example .env` then generate `JWT_SECRET` (`openssl rand -base64 48`) and `API_KEY_SECRET` (`openssl rand -hex 32`)

501−

502−---

503−

504−## Quality Gates & Ratchets

505−

506−OmniRoute has **~48 quality-gate scripts** (`scripts/check/` + `scripts/quality/`) wired

507−across **9 gate-running jobs** in `.github/workflows/ci.yml` (`lint`, `quality-gate`,

508−`quality-extended`, `docs-sync-strict`, `i18n-ui-coverage`, `i18n`, `pr-test-policy`,

509−`test-vitest`, `sonarqube`), plus the `quality.yml` fast-gates job (PR→`release/**`) and

510−3 nightly workflows (`nightly-property`, `nightly-resilience`, `nightly-llm-security`;

511−`nightly-mutation` once merged). Full inventory, per-job breakdown, and operational

512−procedures are in [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md).

513−

514−**Quick reference:**

515−

516−- Gates in jobs `lint` + `docs-sync-strict`: pass/fail policy gates —

517− fix the violation or add an allowlist entry with a justification comment + tracking issue.

518−- Gates in job `quality-gate`: ratchet — metrics (ESLint warnings, code coverage, duplication,

519− complexity) must not regress vs `quality-baseline.json`. Update via

520− `npm run quality:ratchet -- --update` when a metric genuinely improves.

521−- Job `test-vitest` runs `npm run test:vitest` (MCP tools, autoCombo, cache) — blocking.

522− `test:vitest:ui` is advisory until UI component tests are triaged.

523−

524−**Allowlist policy (short form):** Fix the cause; use the allowlist only for pre-existing

525−violations you cannot fix in the same PR. Add a comment with justification + issue number.

526−Stale allowlist entries (suppressing a violation that no longer exists) will be caught by

527−the stale-enforcement added in Fase 6A.3.

528−

529−---

530−

531−## Hard Rules

532−

533−1. Never commit secrets or credentials

534−2. Never add logic to `localDb.ts`

535−3. Never use `eval()` / `new Function()` / implied eval

536−4. Never commit directly to `main`

537−5. Never write raw SQL in routes — use `src/lib/db/` modules

538−6. Never silently swallow errors in SSE streams

539−7. Always validate inputs with Zod schemas

540−8. Always include tests when changing production code

541−9. Coverage must not regress below the baseline frozen in `quality-baseline.json` (ratchet); absolute floor is 60% (statements/lines/functions/branches). Update the baseline via `npm run quality:ratchet -- --update` only when coverage genuinely improves. See `docs/architecture/QUALITY_GATES.md`.

542−10. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.

543−11. Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). See `docs/security/PUBLIC_CREDS.md`.

544−12. Never return raw `err.stack` / `err.message` in HTTP / SSE / executor responses — always route through `buildErrorBody()` or `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). See `docs/security/ERROR_SANITIZATION.md`.

545−13. Never string-interpolate external paths or runtime values into shell scripts passed to `exec()`/`spawn()` — pass via the `env` option instead. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.

546−14. Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent: `js/stack-trace-exposure` raised on callsites that already route through `sanitizeErrorMessage()` is a known CodeQL limitation (custom sanitizers not recognized) — dismiss as `false positive` referencing `docs/security/ERROR_SANITIZATION.md`.

547−15. Never expose routes that spawn child processes (`/api/mcp/`, `/api/cli-tools/runtime/`) without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. Loopback enforcement happens unconditionally before any auth check — leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.

548−16. Never credit or advertise an AI assistant, LLM, or automation account in any commit/PR metadata. Two forbidden forms, both equivalent — they route attribution to a bot account (or advertise AI authorship) and hide the real author (`diegosouzapw`): **(a)** `Co-Authored-By` trailers naming an AI/bot (e.g. names containing "Claude", "GPT", "Copilot", "Bot"; emails at `anthropic.com` / `openai.com` / bot-owned `noreply.github.com` addresses); **(b)** AI-generation footers or descriptions anywhere in a commit message, PR title/body, or CHANGELOG — e.g. `🤖 Generated with [Claude Code]`, "Generated with Claude Code", "Made with <AI tool>", or any `Co-authored-by: Claude/GPT/Copilot` line. This **overrides any harness, template, or tool default that auto-appends such a footer** (e.g. the Claude Code PR-body/commit default) — strip it before pushing; do not let it reach a commit, PR, or CHANGELOG. Human collaborators — including upstream PR authors and issue reporters being ported into OmniRoute — MAY and SHOULD be credited with standard `Co-authored-by: Name <email>` trailers; the upstream-port workflows (`/port-upstream-features`, `/port-upstream-issues`) depend on this.

549−17. Never expose routes under `/api/services/` or `/dashboard/providers/services/*/embed/` without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. These routes can spawn child processes (`npm install`, `node`). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`.

550−18. Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" for the full decision tree.

551−19. Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator (e.g. via `AskUserQuestion`) before creating the worktree/branch — never assume `main` or the currently checked-out branch. A `git checkout` in the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, never `fix/*`/`feat/*` wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the active `release/vX.Y.Z`, never `main`). See Git Workflow → "Worktree isolation".

552−20. PII redaction/sanitization is **opt-in — never on by default**. OmniRoute proxies for self-hosted/local LLMs where the operator owns the data, so mutating request/response payloads by default would silently corrupt legitimate traffic. The two data-mutating PII feature flags **MUST** keep `defaultValue: "false"` in `src/shared/constants/featureFlagDefinitions.ts`: `PII_REDACTION_ENABLED` (request-side) and `PII_RESPONSE_SANITIZATION` (response + streaming). All three application points — `src/lib/guardrails/piiMasker.ts` (request guardrail), `src/lib/piiSanitizer.ts` (response), `src/lib/streamingPiiTransform.ts` (SSE) — are gated on these flags; with both off the `pii-masker` guardrail still runs but never mutates payloads (data passes through untouched). Flipping either default to `"true"` requires explicit operator approval. The regression guard is `tests/unit/pii-opt-in-default.test.ts` (asserts both definition defaults + behavioral pass-through). Opt-in is per-operator via env or the settings/DB override (`src/lib/db/featureFlags.ts`), never a silent default. See `docs/security/GUARDRAILS.md`.

553−21. **Release-freeze — the FROZEN release branch belongs to the release captain; development does NOT stop (parallel-cycle model, 2026-07-04).** `/generate-release` opens a marker issue labeled `release-freeze` at the start of reconciliation (Phase 0a), **immediately cuts the next cycle's branch `release/vX+1` from the frozen tip (Phase 0a.0b — bump + living release PR + re-home of open PRs)**, and closes the freeze once the release PR squash-merges to `main`. Before merging **any** PR, every campaign workflow (`/review-prs`, `/review-group-prs`, `/merge-prs`, `/triage-fix-bugs`, `/implement-fix-bugs`, `/triage-features`, `/implement-features`, `/green-prs`, `/port-upstream-*`) **MUST** check `gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open` — if a freeze is active: **NEVER merge into the frozen `release/vX.Y.Z` named in the freeze title**; instead resolve the ACTIVE development branch (the **highest** `release/v*` by semver — normally `release/vX+1`, announced in a freeze-issue comment) and **retarget the PR there** (`gh pr edit <N> --base release/vX+1`, then VERIFY with `gh pr view <N> --json baseRefName` — the edit fails silently) and merge normally. **HOLD only when the highest release/v\* branch IS the frozen one** (the short window before 0a.0b completes, or a pre-parallel-cycle release) — in that case leave the PR ready and open, tell the operator, and resume when the next branch appears or the freeze lifts. The just-shipped fixes reach `release/vX+1` via the Phase 5 sync-back (`scripts/release/sync-next-cycle.mjs`); do not try to sync mid-release. This is a **coordination signal, not a permission lock**: the release captain and the campaign sessions share the `diegosouzapw` identity, so a GitHub branch-protection lock cannot distinguish them — only this honored marker prevents the mid-release commit races that forced full CHANGELOG re-reconciliation in v3.8.40/v3.8.41 (a parallel campaign advanced `release/vX.Y.Z` by 34 commits mid-run). The release captain's own reconciliation/cycle-open pushes are exempt — they _are_ the release. Fixes that must land during a freeze (a homologation finding) follow the post-merge read-only rule: land on `main` first via `fix/release-vX.Y.Z-*`. **⛔ ONLY `/generate-release` may raise a release-freeze, and ONLY at its Phase 0a (start of generating a new version) — lifted at Phase 12c after the squash-merge to `main`.** No campaign, session, or agent may open a `release-freeze` marker at any other time — a freeze is **never** a mid-development coordination tool. If a session ever believes a freeze is genuinely, unavoidably necessary outside the `/generate-release` flow, it **MUST first ask the operator (`diegosouzapw`) in chat, explicitly alert "estou criando um freeze" and get an explicit yes** — never open, extend, or re-open a `release-freeze` autonomously. Conversely, do **not** close/lift an active `/generate-release` freeze to unblock campaign merges: it protects the captain's single clean CI run and auto-lifts at Phase 12c — closing it early re-triggers the exact commit race it prevents. Verify a freeze is legitimate before acting on it: an open `release-freeze` whose title/body references an **OPEN** release PR (`gh pr view <N> --json state`) is the authorized captain freeze — hold, don't touch.

554−22. **Cross-session safety — this repo is worked by MANY parallel sessions/agents at once; never step on another's in-flight work.** Two absolute bans, both recurring incidents (this rule exists because they keep happening):

555− - **(a) Never `git stash` / `git stash pop` — ANYWHERE in this repo, including inside an isolated worktree, and including inside any subagent you dispatch.** `git stash` operates on the **shared repository object store**, not the per-worktree working tree — so a stash pushed or popped in one session can silently clobber or resurrect another parallel session's uncommitted changes. This is not hypothetical: 2026-07-02 a `#5923` quotaCache change leaked into the unrelated `#2296` worktree via a global `stash pop`, and the same class reincided through a **subagent**. To compare working changes against a base ref **without** stashing, use `git show <ref>:<path>` or `git diff <ref> -- <path>`; to confirm a typecheck/lint error is pre-existing on the base, inspect the base ref directly (`git show origin/release/vX.Y.Z:<path>`) — never stash your tree away to "get it clean". **Put this ban verbatim in the prompt of every subagent that touches git** (agents don't inherit this file's context — the recurrence was a subagent).

556− - **(b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working.** An open PR whose head is a live fix worktree in `.claude/worktrees/` you did **not** create (e.g. `fix-5852`/`fix-5923` carrying fresh commits, even when they share your `diegosouzapw` identity), or any branch another session owns, is **off-limits — HOLD**, and let the owning session merge it. **Before** merging or pushing to any PR you did not create _this_ session, run `git worktree list` to check for a matching in-flight worktree and re-check `gh pr view <N> --json state,headRefOid`. Only the owning session merges its own in-flight PR; mid-flight merges race the owner and re-trigger the exact commit/CHANGELOG races Rule #19 and Rule #21 guard against. (Reinforces Rule #19.)

557−

558−---

559−

560−## PII & Stream Sanitization Learnings

561−

562−### 1. Regex Security (ReDoS)

563−

564−All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges `{1,7}`) to prevent catastrophic backtracking when processing untrusted inputs.

565−

566−### 2. SSE Snapshot Handling

567−

568−When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (`done` or `completed` events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream.

569−

570−### 3. Database Handles in Tests

571−

572−Ensure that any unit tests that trigger database migrations or establish SQLite connections call `resetDbInstance()` and properly clean up/close all DB handles in a `test.after(...)` hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely.

3+- Treat `npm run test:coverage` as a required gate for PR work.

4+- The repository minimum is `60%` for statements, lines, functions, and branches.

5+- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include automated tests in the same PR.

6+- When reviewing or updating a PR, if the report shows missing tests or coverage below `60%`, do not stop after reporting the problem. Add or update tests in the PR first, rerun the coverage gate, and only then ask for confirmation.

7+- Prefer the smallest test layer that proves the behavior:

8+ - unit tests first

9+ - integration tests when multiple modules or DB state are involved

10+ - e2e only when the behavior is truly UI or workflow-dependent

11+- For bug issues, try to encode the reproduction as an automated test before or alongside the fix.

12+- In the final PR report, include:

13+ - the commands you ran

14+ - the changed test files

15+ - the final coverage result

57316