diff --git a/.mcp.json.example b/.mcp.json.example new file mode 100644 index 0000000000..0a11e61a62 --- /dev/null +++ b/.mcp.json.example @@ -0,0 +1,17 @@ +{ + "$comment_purpose": "OPT-IN agent-lsp / LSP-in-the-loop (Quality Gates Fase 7 Task 15). Copy this file to `.mcp.json` to enable. It exposes a TypeScript language server to coding agents (Claude Code, etc.) so they get diagnostics / hover / go-to-definition / blast-radius BEFORE writing code — turning 'invented symbol' review-catches into impossible-at-edit-time. Pairs with `npm run typecheck:core` as a compile-before-claim check.", + "$comment_safety": "Shipped as `.example` (NOT `.mcp.json`) on purpose so it never auto-loads an unvetted server into everyone's session. Pick an MCP<->LSP bridge you trust and have verified locally, then drop in its package + args below. A broken MCP entry only logs a connection error; it does not break agent sessions. The underlying language server is `typescript-language-server` (npm, mature) — install via `npm i -g typescript-language-server typescript` or rely on npx.", + "mcpServers": { + "typescript-lsp": { + "command": "npx", + "args": [ + "-y", + "", + "--lsp", + "typescript-language-server", + "--stdio" + ], + "$note": "Replace with the concrete MCP<->LSP adapter you chose. It must speak MCP on stdio and proxy to `typescript-language-server --stdio`. Scope it to this repo's tsconfig (open-sse/tsconfig.json / tsconfig.json) for accurate diagnostics." + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md index 9ee18e58c4..174e7e30b2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -327,33 +327,33 @@ connection continue serving other models. For any non-trivial change, read the matching deep-dive first: -| Area | Doc | -| -------------------------------------------- | ----------------------------------------------------------------- | -| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` | -| Architecture | `docs/architecture/ARCHITECTURE.md` | -| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` | -| Auto-Combo (9-factor scoring, 15 strategies) | `docs/routing/AUTO-COMBO.md` | -| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` | -| Reasoning replay | `docs/routing/REASONING_REPLAY.md` | -| Skills framework | `docs/frameworks/SKILLS.md` | -| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` | -| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` | -| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` | -| Public upstream credentials (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` | -| Error message sanitization | `docs/security/ERROR_SANITIZATION.md` | -| Evals | `docs/frameworks/EVALS.md` | -| Compliance / audit | `docs/security/COMPLIANCE.md` | -| Webhooks | `docs/frameworks/WEBHOOKS.md` | -| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` | -| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` | -| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | -| MCP server | `docs/frameworks/MCP-SERVER.md` | -| A2A server | `docs/frameworks/A2A-SERVER.md` | -| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` | -| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` | -| Release flow | `docs/ops/RELEASE_CHECKLIST.md` | -| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` | -| Quality gates (35 gates, allowlist policy) | `docs/architecture/QUALITY_GATES.md` | +| Area | Doc | +| --------------------------------------------- | ----------------------------------------------------------------- | +| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` | +| Architecture | `docs/architecture/ARCHITECTURE.md` | +| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` | +| Auto-Combo (9-factor scoring, 15 strategies) | `docs/routing/AUTO-COMBO.md` | +| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` | +| Reasoning replay | `docs/routing/REASONING_REPLAY.md` | +| Skills framework | `docs/frameworks/SKILLS.md` | +| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` | +| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` | +| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` | +| Public upstream credentials (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` | +| Error message sanitization | `docs/security/ERROR_SANITIZATION.md` | +| Evals | `docs/frameworks/EVALS.md` | +| Compliance / audit | `docs/security/COMPLIANCE.md` | +| Webhooks | `docs/frameworks/WEBHOOKS.md` | +| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` | +| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` | +| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | +| MCP server | `docs/frameworks/MCP-SERVER.md` | +| A2A server | `docs/frameworks/A2A-SERVER.md` | +| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` | +| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` | +| Release flow | `docs/ops/RELEASE_CHECKLIST.md` | +| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` | +| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md` | --- @@ -422,13 +422,17 @@ git push -u origin feat/your-feature ## Quality Gates & Ratchets -OmniRoute has **35 CI quality gates** wired across 6 jobs in `.github/workflows/ci.yml`. -Full inventory, per-job breakdown, and operational procedures are in -[`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md). +OmniRoute has **~48 quality-gate scripts** (`scripts/check/` + `scripts/quality/`) wired +across **9 gate-running jobs** in `.github/workflows/ci.yml` (`lint`, `quality-gate`, +`quality-extended`, `docs-sync-strict`, `i18n-ui-coverage`, `i18n`, `pr-test-policy`, +`test-vitest`, `sonarqube`), plus the `quality.yml` fast-gates job (PR→`release/**`) and +3 nightly workflows (`nightly-property`, `nightly-resilience`, `nightly-llm-security`; +`nightly-mutation` once merged). Full inventory, per-job breakdown, and operational +procedures are in [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md). **Quick reference:** -- Gates in job `lint` (18 checks) + `docs-sync-strict` (12 checks): pass/fail policy gates — +- Gates in jobs `lint` + `docs-sync-strict`: pass/fail policy gates — fix the violation or add an allowlist entry with a justification comment + tracking issue. - Gates in job `quality-gate`: ratchet — metrics (ESLint warnings, code coverage, duplication, complexity) must not regress vs `quality-baseline.json`. Update via diff --git a/docs/architecture/QUALITY_GATES.md b/docs/architecture/QUALITY_GATES.md index 0d62acb453..420d5257e9 100644 --- a/docs/architecture/QUALITY_GATES.md +++ b/docs/architecture/QUALITY_GATES.md @@ -13,7 +13,7 @@ in `CLAUDE.md`. --- -## Gate Inventory (35 scripts) +## Gate Inventory (~48 scripts) Scripts live under `scripts/check/` (policy gates) and `scripts/quality/` (ratchet engine). The CI source of truth is `.github/workflows/ci.yml`. @@ -188,6 +188,18 @@ allowlist is a false sense of quality. --- +## Agent tooling: LSP-in-the-loop (opt-in) + +Beyond the CI gates, OmniRoute ships an **opt-in** `agent-lsp` scaffold +([`.mcp.json.example`](../../.mcp.json.example), Fase 7 Task 15). Copy it to `.mcp.json` +to expose a TypeScript language server to coding agents, so they resolve symbols / +diagnostics **before** writing code — a compile-before-claim companion to +`typecheck:core` that cuts "invented symbol" errors at the source. It is intentionally +not auto-loaded (you pick and verify the MCP↔LSP bridge); a broken entry only logs a +connection error and never breaks sessions. + +--- + ## Related Documentation - Supply-chain (provenance, SBOM, Trivy, Scorecard): [`docs/security/SUPPLY_CHAIN.md`](../security/SUPPLY_CHAIN.md)