@fitsummehari/mergeguard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/). `0.1.0` is the first public beta. There is no prior public npm release of this local-first CLI.
+
+## 0.1.0
+
+First public beta of MergeGuard as a local-first semantic pre-push / code-change gate.
+
+- Single review engine shared by the CLI, Git pre-push hook, GitHub Actions, GitLab CI, generic CI, and the Node API
+- Working-tree, staged, `--base`/`--head`, and pre-push Git scopes, including first commits and first pushes against Git's empty tree
+- High-signal detectors for security, authorization, tenant isolation, concurrency, database integrity, and related runtime risk
+- Bounded ephemeral repository context (no persisted project database)
+- Published as `@fitsummehari/mergeguard` (CLI binary remains `mergeguard`; unscoped `mergeguard` is a different npm package)
+- Deterministic `offline` verifier by default (reproducible); `auto` and local Laya optional; optional Jev
+- Terminal, JSON, SARIF, and GitLab Code Quality reporters
+- Non-destructive, idempotent hook install/uninstall that respects `core.hooksPath`
+- Zero runtime npm dependencies; Node.js 20+; Laya model weights are not bundled

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MergeGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# MergeGuard
+
+MergeGuard is a local-first semantic code-change gate that catches high-impact bugs before code is pushed or merged.
+
+It reviews a Git diff — not an entire repository — for concrete runtime risks such as authorization regressions, tenant-isolation holes, check-then-write races, unsafe SQL or shell construction, and removed transaction boundaries. It is not a SaaS platform and not a style linter.
+
+```text
+Git diff
+   ↓
+MergeGuard review engine
+   ├── deterministic/static detectors
+   ├── repository/context resolver
+   └── optional semantic verifier
+         ├── local Laya
+         └── optional Jev/provider
+   ↓
+normalized findings
+   ↓
+terminal / JSON / SARIF / GitLab
+   ↓
+PASS / BLOCK
+```
+
+The same engine is used by the CLI, a Git pre-push hook, GitHub Actions, GitLab CI, other CI systems, and the programmatic Node API.
+
+```bash
+npm install -D @fitsummehari/mergeguard
+npx mergeguard review
+```
+
+Requires only **Node.js 20+** and **Git** for the default offline experience. The CLI binary is `mergeguard`; the npm package is scoped because the unscoped name is owned by a different project.
+
+## Why it exists
+
+Compilers, tests, and formatters do not reliably catch "this change will fail under concurrency" or "this query no longer filters by tenant." MergeGuard sits in front of `git push` and CI so those classes of defect can block the change with a normal process exit code. No MergeGuard server, database, dashboard, GitHub App, or webhook service is required.
+
+## What it catches
+
+High-signal, change-scoped risks, including:
+
+- authorization / route-protection regressions
+- tenant or ownership filter removal
+- check-then-create and read-check-write races
+- missing uniqueness / idempotency around creates and webhooks
+- removed transaction boundaries and non-atomic related writes
+- unbounded deletes or empty-filter updates
+- SQL injection, command injection, dynamic evaluation
+- unsafe deserialization and path traversal
+- XSS / raw HTML sinks where the sink is visible
+- disabled TLS verification
+- async `forEach`, swallowed errors, N+1 query and unbounded fan-out candidates
+- validation removal and insecure framework markers such as `@Public()` / `[AllowAnonymous]`
+
+## What it deliberately does not catch
+
+MergeGuard is not a style linter and will not report:
+
+- semicolons, quotes, import order, or naming taste
+- formatting or line length
+- generic "consider refactoring" advice
+- documentation nags
+- arbitrary function-length opinions
+- subjective AI code-review commentary
+
+It is also not a CVE database, secret scanner, compiler, or test runner.
+
+## Installation
+
+```bash
+npm install -D @fitsummehari/mergeguard
+npx mergeguard review
+```
+
+Zero runtime npm dependencies. Python is **not** required for default operation.
+
+### One-off invocation without a local install
+
+Do **not** run bare `npx mergeguard` before installing — npm may resolve the unrelated unscoped `mergeguard` package.
+
+```bash
+npx --package=@fitsummehari/mergeguard mergeguard review
+```
+
+After a normal local install, `npx mergeguard review` is correct because npm uses the local binary.
+
+### From this source tree
+
+```bash
+node bin/mergeguard.js review
+```
+
+## 30-second quick start
+
+```bash
+cd your-git-repo
+npm install -D @fitsummehari/mergeguard
+npx mergeguard review
+```
+
+That reviews the working tree (staged, unstaged, and untracked) against `HEAD`. Exit `0` means pass. Exit `1` means a blocking finding. Exit `2` means MergeGuard or the environment failed. The default verifier is **offline** (reproducible across machines).
+
+## Local review
+
+```bash
+npx mergeguard review
+npx mergeguard review --staged
+npx mergeguard review --base origin/main
+npx mergeguard review --base origin/main --head HEAD
+npx mergeguard review --verifier offline
+```
+
+`--no-ai` and `--verifier offline` / `--verifier deterministic` force the built-in verifier.
+
+## Pre-push hook
+
+```bash
+npx mergeguard hook install
+npx mergeguard hook status
+npx mergeguard hook uninstall
+```
+
+Install is idempotent and will not overwrite an existing pre-push hook. It appends a marked MergeGuard block and respects `core.hooksPath` when set. The hook reads Git's pre-push stdin and reviews the outgoing commit range, including first pushes (diffed against Git's empty tree).
+
+If MergeGuard blocks a push, it tells you how to bypass **only when relevant**:
+
+```bash
+git push --no-verify
+```
+
+Use CI as the enforcement layer. Local hooks are a convenience, not a security boundary.
+
+## GitHub Actions
+
+```bash
+npx mergeguard ci github --write
+```
+
+Or copy [`examples/github/mergeguard.yml`](examples/github/mergeguard.yml). Default templates install `@fitsummehari/mergeguard`, pin `--verifier offline`, and can upload SARIF. Make the job a required check if you want enforcement. Optional Laya-in-CI recipes are in [docs/LAYA.md](docs/LAYA.md).
+
+## GitLab CI
+
+```bash
+npx mergeguard ci gitlab --write
+```
+
+Or copy [`examples/gitlab/mergeguard.yml`](examples/gitlab/mergeguard.yml). The job writes GitLab Code Quality JSON as an artifact and still uses the CLI exit code to block.
+
+## Other CI
+
+Any runner with Git and Node 20+ can run the same engine after installing the scoped package:
+
+```bash
+npm install -D @fitsummehari/mergeguard
+npx mergeguard review --verifier offline --base <base> --head <head>
+```
+
+That works on Jenkins, CircleCI, Azure DevOps, Bitbucket, Buildkite, and custom CI. No provider credentials are required for offline verification.
+
+## Configuration
+
+Zero-config defaults to the offline verifier. To pin policy:
+
+```bash
+npx mergeguard init
+```
+
+This writes `.mergeguard.yml` and will not overwrite an existing file unless you pass `--force`.
+
+```yaml
+fail_on: high
+
+exclude:
+  - dist/**
+  - build/**
+  - generated/**
+  - vendor/**
+  - node_modules/**
+
+review:
+  security: true
+  correctness: true
+  concurrency: true
+  database: true
+  performance: true
+
+verifier:
+  engine: offline
+```
+
+`fail_on` may be `critical`, `high`, `medium`, `low`, `info`, or `none`. Unknown root keys produce a warning. Malformed YAML reports the file path and line. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
+
+`auto` is available but environment-dependent (uses Laya when installed). Prefer pinning `offline` or `laya` for team/CI reproducibility. `mergeguard doctor` shows configured vs effective verifier.
+
+## Output formats
+
+```bash
+npx mergeguard review --format terminal
+npx mergeguard review --format json
+npx mergeguard review --format sarif --output mergeguard.sarif
+npx mergeguard review --format gitlab --output gl-code-quality-report.json
+```
+
+Machine-readable formats write only the report to stdout (or `--output`). Status goes to stderr so JSON/SARIF/GitLab output stays parseable.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Review completed; no blocking finding |
+| `1` | Review completed; policy blocked the change |
+| `2` | MergeGuard, config, Git, or runtime failure |
+
+## Optional Laya
+
+Laya is **not** bundled with the npm package. MergeGuard works without it. Keeping model weights out of npm keeps the install small (~40 KB) and lets default CI run on Node alone.
+
+```bash
+python -m pip install laya
+npx mergeguard doctor
+npx mergeguard review --verifier laya
+```
+
+`--verifier laya` exits `2` with an install hint if Laya is missing. It does **not** silently fall back. See [docs/LAYA.md](docs/LAYA.md).
+
+MergeGuard talks to Laya through a short-lived local Python process over stdin/stdout. It does not start an HTTP server. First model use may download a checkpoint into the Hugging Face cache.
+
+## Optional Jev
+
+Jev is opt-in and never required for default operation.
+
+```bash
+export TYPESAFE_API_KEY=...   # or JEV_API_KEY
+npx mergeguard review --verifier jev
+```
+
+Jev sends candidate evidence to the configured HTTP API. Secrets are read from the environment and are not printed.
+
+## Programmatic API
+
+```js
+import { review } from "@fitsummehari/mergeguard";
+
+const result = await review({
+  cwd: process.cwd(),
+  base: "origin/main",
+  head: "HEAD",
+});
+
+// result.passed, result.findings, result.summary, result.metadata
+if (!result.passed) process.exitCode = 1;
+```
+
+Also exported: `reviewChangeSet`, `loadConfig`, `normalizeConfig`, `renderReport`, `toSarif`, `toGitLabCodeQuality`, `detectLaya`, `VERSION`. Everything else is internal.
+
+## Language-support philosophy
+
+MergeGuard **runs on any normal Git repository**. That is not the same as equal deep semantics for every language.
+
+JavaScript, TypeScript, Python, Java, Kotlin, Go, C#, PHP, Ruby, and SQL have additional syntax-aware rules. Rust, C, C++, shell, YAML, JSON, Terraform, Dockerfiles, and mixed monorepos still get generic analysis and must not crash merely because a deeper adapter is missing.
+
+## Limitations
+
+- Findings are candidates plus a verifier, not proofs.
+- Context is bounded — not a persisted project database.
+- Huge diffs are truncated; generated/minified/binary paths are skipped.
+- Local hooks can be bypassed with `--no-verify`.
+- Semantic depth varies by language and framework.
+
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md) and [docs/DETECTORS.md](docs/DETECTORS.md).
+
+## Security and privacy
+
+Analyzed repository text is treated as untrusted data, never as instructions or executable code. Offline mode makes no network calls. Laya mode stays on the machine aside from Laya/Hugging Face model-cache behavior. Jev mode is explicit and sends candidate context to the configured API.
+
+Do not put credentials in `.mergeguard.yml`. See [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/FitsumMehari/MergeGuard.git
+cd MergeGuard
+npm test
+npm run check
+```
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security
+
+MergeGuard reviews untrusted repository text. That text is evidence only. It is never executed, never sourced as configuration code, and never treated as verifier instructions.
+
+## Reporting a vulnerability
+
+This project does not publish a dedicated security email. Please use [GitHub private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability) on [FitsumMehari/MergeGuard](https://github.com/FitsumMehari/MergeGuard/security/advisories/new) if the repository has that feature enabled.
+
+Maintainers: enable **Settings → Code security → Private vulnerability reporting** so researchers have a private channel.
+
+If private reporting is unavailable, open a GitHub issue titled "Security: please contact maintainers" with no exploit details and wait for a maintainer to reply privately.
+
+## Privacy model
+
+- **Offline / deterministic:** no network calls.
+- **Laya:** local Python process. Laya/Hugging Face may download a model checkpoint into a local cache on first use.
+- **Jev:** explicit opt-in. Candidate context is sent to the configured HTTP API. Credentials come from `TYPESAFE_API_KEY` or `JEV_API_KEY` and must not be placed in `.mergeguard.yml` or committed.
+
+Do not include secrets in reports, fixtures, or configuration examples.
+
+## Trust boundary
+
+- Git filenames, diffs, and file contents from the reviewed repository are untrusted.
+- MergeGuard must not run scripts from that repository.
+- Analyzed paths are constrained to the repository root.
+- Binary, oversized, and ignored files are skipped.

package/bin/mergeguard.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (error) => {
+    console.error(`mergeguard: ${error?.message || error}`);
+    if (process.env.MERGEGUARD_DEBUG === "1" && error?.stack) console.error(error.stack);
+    process.exit(2);
+  },
+);

package/docs/ARCHITECTURE.md

@@ -0,0 +1,31 @@
+# Architecture
+
+MergeGuard is a single-process CLI and Node library. There is no application server, database, queue, dashboard, or webhook listener.
+
+```text
+CLI / hook / CI / JS API
+    │
+    ├─ Git scope resolver
+    │    working | staged | branch range | pre-push
+    │
+    ├─ detector pipeline
+    │    pattern detectors
+    │    diff-regression detectors
+    │    repository-aware detectors
+    │
+    ├─ context resolver
+    │    changed files + nearby high-signal files
+    │    manifests / schemas / auth / migrations
+    │
+    ├─ verifier
+    │    offline (built-in)
+    │    Laya (local Python, optional)
+    │    Jev (remote, optional)
+    │
+    └─ reporters
+         terminal | JSON | SARIF | GitLab Code Quality
+```
+
+Public library types live in `src/types.js` (`ReviewResult`, `Finding`, `ChangedFile`, severity/category). Additional detectors, language adapters, verifiers, and reporters should plug into this pipeline rather than forking it.
+
+Repository context is resolved per review and discarded. Nothing is persisted.

package/docs/CONFIGURATION.md

@@ -0,0 +1,59 @@
+# Configuration
+
+MergeGuard works with no config file. When present, it reads the first of:
+
+- `.mergeguard.yml`
+- `.mergeguard.yaml`
+- `.mergeguard.json`
+
+Or `--config PATH`. `mergeguard init` writes a conservative `.mergeguard.yml` and refuses to overwrite unless `--force` is passed.
+
+## Defaults
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `fail_on` | `high` | Also accepts `failOn`. Values: `critical`, `high`, `medium`, `low`, `info`, `none` |
+| `verifier.engine` | `offline` | `offline` (default, reproducible), `deterministic` (alias), `auto` (Laya if installed), `laya`, `jev` |
+| `confidence` | `0.62` | Verifier strength threshold in `0..1` |
+| `exclude` | `node_modules/**`, `vendor/**`, `dist/**`, `build/**`, `coverage/**`, `.next/**`, `.git/**`, `**/*.min.js`, `**/*.map`, `**/generated/**` | Also accepts `ignore` / `ignore.paths` |
+| `review.*` | all categories `true` | Disable a category with `false` |
+| `max_files` | `300` (cap 5000) | Changed files analyzed |
+| `max_candidates` | `120` (cap 1000) | Detector candidates kept |
+| `context_files` | `24` (cap 100) | Nearby files loaded as evidence |
+| `context_chars` | `18000` (cap 200000) | Evidence budget per candidate |
+
+Unknown root keys are ignored with a warning that includes the config path.
+
+## Example
+
+```yaml
+fail_on: high
+exclude:
+  - dist/**
+  - generated/**
+review:
+  security: true
+  performance: false
+verifier:
+  engine: offline
+laya:
+  python: python3
+  max_len: 4096
+```
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `MERGEGUARD_PYTHON` | Python executable for Laya |
+| `MERGEGUARD_LAYA_TIMEOUT_MS` | Laya subprocess timeout (default 180000) |
+| `MERGEGUARD_JEV_TIMEOUT_MS` | Jev HTTP timeout (default 30000) |
+| `TYPESAFE_API_KEY` / `JEV_API_KEY` | Jev only |
+| `MERGEGUARD_BIN` | Pre-push hook executable override |
+| `MERGEGUARD_REMOTE` | Remote name passed into the hook |
+| `MERGEGUARD_DEBUG=1` | Print stack traces on CLI failures |
+| `NO_COLOR` | Disable ANSI color |
+
+## Limits
+
+Tracked-file scoring for context is capped at 4000 paths. Individual file reads stop at 2 MiB and skip binary (NUL) content. Symlinks that escape the repository root are not read.

package/docs/DETECTORS.md

@@ -0,0 +1,29 @@
+# Detector coverage
+
+MergeGuard runs only against changed content/diff regressions and then adds bounded repository context.
+
+## High-signal categories
+
+| Category | Examples |
+|---|---|
+| Security | dynamic evaluation, SQL injection candidates, shell injection, TLS verification disabled, raw HTML, unsafe deserialization, path traversal, sensitive logging |
+| Authorization | auth guard/policy removal, anonymous/public access introduced, token decode without visible verification |
+| Tenant isolation | tenant/organization/owner predicates removed; repository-aware missing isolation candidates |
+| Concurrency | check-then-create, read-check-write, webhook replay/idempotency candidates |
+| Database | transaction removal, multi-write atomicity, broad delete/update, uniqueness removal, risky migrations |
+| Correctness/reliability | async forEach, swallowed exceptions, unsafe retry behavior, input-validation removal, hard-coded local endpoints |
+| Performance | N+1 query candidates, unbounded async fan-out, potentially blocking index creation |
+
+## Language-aware rules
+
+The generic layer runs in any text Git repository. Additional direct rules currently recognize JavaScript/TypeScript, Python, Java/Kotlin, Go, PHP, Ruby, C#, SQL and common configuration forms. C/C++, Rust, shell, Terraform, Dockerfiles and other languages still benefit from generic diff-regression, TLS/SQL/configuration, repository and migration checks, but have fewer syntax-specific rules today. `yaml.load` is ignored when `SafeLoader` is present on the same line.
+
+## Stack/context recognition
+
+The context resolver recognizes common signals for NestJS, Next.js, Express, Fastify, Django, FastAPI, Flask, Spring, Laravel, Symfony, Rails, ASP.NET Core, Gin/Fiber, Actix/Axum; Prisma, TypeORM, Sequelize, SQLAlchemy, Entity Framework, GORM, Hibernate, Diesel/SQLx; PostgreSQL, MySQL/MariaDB, MongoDB, SQLite and Redis.
+
+Recognition does not imply perfect semantic parsing. It is used to select useful evidence and reduce false positives.
+
+## What is intentionally excluded
+
+MergeGuard does not compete with formatters/linters on formatting, naming, import order, line length or generic maintainability opinions. It also does not include a vulnerability-database service, dependency CVE feed, secret-management backend, compiler or test runner.

package/docs/INTEGRATIONS.md

@@ -0,0 +1,40 @@
+# Integrations
+
+All surfaces call the same `review()` engine.
+
+Install once:
+
+```bash
+npm install -D @fitsummehari/mergeguard
+```
+
+Do not install the unscoped name `mergeguard` (different package). Do not use bare `npx mergeguard` until the scoped package is installed locally; for a one-off:
+
+```bash
+npx --package=@fitsummehari/mergeguard mergeguard review
+```
+
+## Local
+
+`mergeguard review` compares the working tree (including untracked files) with `HEAD`. `--staged` limits the review to the index. Default verifier is `offline`.
+
+## Pre-push
+
+`mergeguard hook install` adds a managed block to the pre-push hook (including `core.hooksPath`). Git supplies local/remote refs on stdin; MergeGuard reviews the outgoing range. Existing hook content is retained.
+
+## GitHub
+
+See [`examples/github/mergeguard.yml`](../examples/github/mergeguard.yml). Use `fetch-depth: 0` so merge-base works. Default templates pin `--verifier offline`. Optional Laya CI is in [LAYA.md](LAYA.md).
+
+## GitLab
+
+See [`examples/gitlab/mergeguard.yml`](../examples/gitlab/mergeguard.yml). `--format gitlab` writes Code Quality JSON. Use `artifacts: when: always` so findings upload even when the gate exits `1`.
+
+## Jenkins / CircleCI / Azure DevOps / Bitbucket / Buildkite / custom
+
+```bash
+npm install -D @fitsummehari/mergeguard
+npx mergeguard review --verifier offline --base origin/main --head HEAD
+```
+
+The contract is the exit code plus optional JSON/SARIF/GitLab output. No provider API credentials are required for offline verification.

package/docs/LAYA.md

@@ -0,0 +1,82 @@
+# Optional Laya verification
+
+Laya is **not** bundled in the MergeGuard npm package. Detectors run in Node. Laya is an optional verifier that answers narrow questions (plausible, reachable, already protected, impact, worth reporting) about those candidates.
+
+MergeGuard works with **Node.js 20+ and Git only**. Python and Laya are extra.
+
+```bash
+python -m pip install laya
+npx mergeguard doctor
+npx mergeguard review --verifier laya
+```
+
+On first model-backed use, Laya may download a checkpoint into its normal local Hugging Face cache. Later runs can reuse that cache. Do not commit model files. Do not put hundreds of millions of parameters into the npm tarball.
+
+## Reproducibility
+
+Default for 0.1.0 is `offline` so laptop and CI agree without Python.
+
+`auto` uses Laya when it is importable and otherwise falls back to offline. That can make environments disagree. Prefer pinning:
+
+```yaml
+verifier:
+  engine: offline
+```
+
+or, if every environment installs Laya:
+
+```yaml
+verifier:
+  engine: laya
+```
+
+`mergeguard doctor` shows configured vs effective verifier.
+
+## Optional GitHub Actions (Laya)
+
+Do **not** add this to the default lightweight workflow.
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+- run: npm install --save-dev @fitsummehari/mergeguard
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.11"
+- run: python -m pip install laya
+- uses: actions/cache@v4
+  with:
+    path: |
+      ~/.cache/huggingface
+    key: laya-hf-${{ runner.os }}
+- run: npx mergeguard review --verifier laya --base "origin/${{ github.base_ref }}" --head "${{ github.event.pull_request.head.sha }}"
+```
+
+## Optional GitLab CI (Laya)
+
+```yaml
+mergeguard-laya:
+  image: node:22
+  before_script:
+    - apt-get update && apt-get install -y python3 python3-pip
+    - python3 -m pip install laya
+    - npm install --save-dev @fitsummehari/mergeguard
+  cache:
+    paths:
+      - .cache/huggingface/
+  variables:
+    HF_HOME: "$CI_PROJECT_DIR/.cache/huggingface"
+  script:
+    - npx mergeguard review --verifier laya --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head "$CI_COMMIT_SHA"
+```
+
+## Future Node-native path
+
+`@receptron/laya` exists on npm (0.1.x) and can load ONNX weights from a local cache. That release is too early to take as a MergeGuard runtime dependency. 0.1.0 keeps the Python subprocess bridge. A later version may optionally call:
+
+```text
+MergeGuard Node → Laya ONNX/TypeScript runtime → model cached locally
+```
+
+without putting hundreds of millions of parameters inside the npm tarball.

package/docs/LIMITATIONS.md

@@ -0,0 +1,10 @@
+# Limitations
+
+- MergeGuard **runs on arbitrary Git repositories**. It does **not** have equal semantic analysis for every language or framework.
+- Detectors produce candidates. The verifier can suppress weak ones. Neither is a formal proof.
+- Context is ephemeral and bounded. MergeGuard does not build or persist a whole-repository "project brain."
+- Large diffs are truncated (`max_files`). Generated, minified, binary, and excluded paths are skipped.
+- First-push and root-commit reviews use Git's empty tree. Shallow clones still need enough history for `--base` merge-base resolution.
+- Pre-push hooks can be bypassed with `git push --no-verify`.
+- Default verifier is `offline`. `auto` does not fail when Laya is missing and can make laptop vs CI results differ. Only `--verifier laya` (or `verifier.engine: laya`) requires Laya.
+- Jev is optional, network-using, and credential-gated. Default operation never needs it.

package/docs/MIGRATION_FROM_V1.md

@@ -0,0 +1,27 @@
+# Migration from the hosted 1.x shape
+
+The previous repository modeled MergeGuard as a hosted review platform. The 2.x local-first shape removes the infrastructure layer and keeps the review capability as a CLI/library.
+
+## Removed
+
+- `apps/api`
+- `apps/web`
+- `apps/worker`
+- database/Prisma persistence
+- Redis/BullMQ queues
+- webhook receivers
+- Docker deployment topology
+- dashboard/authentication concerns
+- persisted repository indexing and analysis-run history
+
+## Replaced by
+
+- `src/git.js`: Git working/staged/range/pre-push change acquisition
+- `src/detectors/*`: diff and repository-aware candidate detection
+- `src/context.js`: bounded ephemeral repository context
+- `src/verifiers/*`: deterministic, local Laya and optional Jev verifier contract
+- `src/reporters/*`: terminal, JSON, SARIF and GitLab Code Quality
+- `src/hook.js`: composable pre-push installation
+- `src/review.js`: one reusable engine used by CLI and JS API
+
+The migration intentionally does not preserve hosted analysis history because persistence is not required by the core product. If a future organization dashboard is needed, it should consume MergeGuard's JSON/SARIF output as a separate optional product rather than being required to run the analyzer.