# KHY-OS vs LibreChat Gap Remediation Roadmap

Updated: 2026-05-15  
Scope: `/home/kodehu03/Khy-OS` vs `/tmp/librechat_cmp/LibreChat-main`

## 1. Goal

Within 4 weeks, close core engineering gaps in testing, CI quality gates, observability, permission model, and release governance, so KHY-OS can sustain faster and safer iteration.

## 2. Baseline (from current comparison)

- CI workflows: KHY `5` vs LibreChat `26`
- Test-related files: KHY `230` vs LibreChat `610`
- E2E coverage files: KHY `1` vs LibreChat `23`
- TS footprint: KHY `8` vs LibreChat `2218`
- Helm chart support: KHY `none` vs LibreChat `present`
- Husky pre-commit workflow: KHY `none` vs LibreChat `present`
- Frontend locale directories: KHY `0` vs LibreChat `41`

## 3. Priority Matrix

## P0 (must complete first, production risk)

1. Frontend automated tests and CI enforcement
2. Unified root scripts (`build/test/lint/e2e`) and pipeline quality gates
3. Observability baseline (`/metrics`, request latency/error metrics, basic tracing hooks)
4. License and metadata consistency fix (repo LICENSE vs package metadata)
5. De-duplication strategy for `backend` and `ai-backend` gateway code

## P1 (important, platform maturity)

1. Fine-grained capability/grant permission model (beyond `admin/user`)
2. Frontend i18n architecture baseline
3. Security/governance docs: `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`

## P2 (scalability and ecosystem)

1. Deployment matrix hardening (Helm or equivalent deployment template)
2. Stronger dependency governance (`overrides`/pin policy, dependency drift checks)

## 4. 4-Week Execution Plan

## Week 1 (P0 start: test + CI)

Deliverables:

1. Add frontend unit test framework and at least smoke tests for auth, routing, core views.
2. Introduce root-level scripts:
   - `test`
   - `test:frontend`
   - `test:backend`
   - `e2e`
3. Update CI to block merge on:
   - frontend tests
   - backend tests
   - lint
   - build

Exit criteria:

1. PR fails if frontend tests fail.
2. CI duration and pass rate are measurable in workflow summary.

## Week 2 (P0 continue: observability + legal consistency)

Deliverables:

1. Add `/metrics` endpoint with auth protection token.
2. Add counters/histograms:
   - request total
   - request latency
   - error total
3. Add structured startup/runtime logs for key services (gateway, auth, proxy).
4. Resolve license inconsistency across:
   - `LICENSE`
   - `pyproject.toml`
   - `backend/package.json`
   - release docs

Exit criteria:

1. Metrics scrape works in local and containerized run.
2. License statement is single-source consistent.

## Week 3 (P0/P1: architecture risk + permissions)

Deliverables:

1. Decide and implement gateway consolidation pattern:
   - shared package extraction, or
   - strict single-owner module with imports
2. Remove drift between duplicated gateway files.
3. Introduce capability-based permission checks for selected admin APIs.
4. Add regression tests for permission escalation and denial paths.

Exit criteria:

1. No duplicated gateway logic without declared ownership.
2. Permission tests cover both allow/deny flows.

## Week 4 (P1/P2: governance + i18n + deployment)

Deliverables:

1. Add governance docs:
   - `CONTRIBUTING.md`
   - `SECURITY.md`
   - `CODE_OF_CONDUCT.md`
2. Establish frontend i18n baseline:
   - locale directory
   - language switch mechanism
   - fallback policy
3. Add deployment template hardening (Helm or equivalent) and quick-start verification.

Exit criteria:

1. New contributor can run lint/test/build by docs only.
2. At least two languages render core UI text.
3. Deployment template passes a clean environment smoke test.

## 5. Acceptance Metrics (end of week 4)

1. CI required checks ≥ 8 and all blocking on PR.
2. Frontend automated tests exist and run in CI.
3. E2E scenario count > current baseline and includes login + critical path.
4. `/metrics` available with protected access.
5. License and package metadata fully consistent.
6. Gateway duplication removed or formally centralized.
7. Capability-based access control live on admin critical paths.

## 6. Risk Control

1. Keep each week as an independent milestone; do not stack unfinished P0 into P2.
2. Any refactor touching gateway/auth must be guarded by regression tests first.
3. Do not widen permissions or bypass checks for temporary convenience.
4. If CI runtime grows too much, shard tests and cache dependencies before reducing coverage.

## 7. Suggested Owners

1. Runtime/Backend lead: observability, gateway consolidation, permission model
2. Frontend lead: test setup, i18n baseline
3. DevOps lead: CI quality gates, deployment template
4. Repo maintainer: governance docs and license alignment

