vibe-gate-mcp 0.1.0

package/docs/INSTALLATION.md

@@ -0,0 +1,104 @@
+# Installation Guide
+
+## Prerequisites
+
+- **Node.js** ≥24
+- A Critic LLM API key (see [`.env.example`](../.env.example))
+
+## Consumers (npm) — recommended
+
+### 1. Configure keys
+
+You need **one** provider. Put keys in MCP `env` and/or a `.env` file loaded by vibe-gate.
+
+Minimal (OpenAI):
+
+```env
+CRITIC_PROVIDER=openai
+OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+```
+
+OpenCode:
+
+```env
+CRITIC_PROVIDER=opencode
+OPENCODE_API_KEY=...
+OPENCODE_PLAN=go
+CRITIC_MODEL=minimax-m3
+```
+
+See [project/VARIABLES.md](project/VARIABLES.md) for every variable.
+
+### 2. Cursor MCP
+
+Copy [examples/cursor-mcp.project.json](../examples/cursor-mcp.project.json) into your project’s `.cursor/mcp.json` (or user MCP), and add your key:
+
+```json
+{
+  "mcpServers": {
+    "vibe-gate": {
+      "command": "npx",
+      "args": ["-y", "vibe-gate-mcp"],
+      "env": {
+        "VIBE_WORKSPACE_ROOT": "${workspaceFolder}",
+        "CRITIC_PROVIDER": "openai",
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+`${workspaceFolder}` is required so `files[]` resolves inside the open repo.
+
+### 3. Use `files[]`
+
+```json
+{
+  "phaseId": "my-feature",
+  "report": "…",
+  "files": ["src/a.ts"],
+  "round": 1
+}
+```
+
+## Developers (this repository)
+
+```bash
+git clone https://github.com/mustafacagri/vibe-gate-mcp.git
+cd vibe-gate-mcp
+corepack yarn install
+npm run build
+cp .env.example .env   # fill Critic key — REQUIRED before reviews work
+npm test
+```
+
+Local MCP template: [examples/cursor-mcp.user-local-dev.json](../examples/cursor-mcp.user-local-dev.json).
+
+After rebuild: **toggle** vibe-gate MCP (do not rely on Reload Window alone).
+
+## Multi-repo layout
+
+| Layer              | Responsibility                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| User / project MCP | `npx -y vibe-gate-mcp` (or `node dist/index.mjs` while developing) + `VIBE_WORKSPACE_ROOT=${workspaceFolder}` + Critic key env |
+| Consumer repo      | Agents call `submit_phase_review` with `files[]`                                                                               |
+
+Never hardcode one consumer absolute path as `VIBE_WORKSPACE_ROOT`.
+
+## Publish checklist
+
+```bash
+npm run prepublishOnly
+npm pack --dry-run
+npm publish
+```
+
+Package name on npm: **`vibe-gate-mcp`** (`bin`: `vibe-gate-mcp` → `dist/index.mjs`).
+
+## References
+
+- [USAGE.md](USAGE.md)
+- [SEMANTIC_DIFF_PAYLOAD.md](SEMANTIC_DIFF_PAYLOAD.md)
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+- [project/VARIABLES.md](project/VARIABLES.md)

package/docs/SEMANTIC_DIFF_PAYLOAD.md

@@ -0,0 +1,76 @@
+# Semantic diff payload sources
+
+`submit_phase_review` always reviews a **FILE:…CONTENT:** corpus (full file bodies, not git diff). Agents choose **exactly one** payload source:
+
+| Priority          | Field              | When to use                                                                             |
+| ----------------- | ------------------ | --------------------------------------------------------------------------------------- |
+| **1 (preferred)** | `files: string[]`  | Normal batches. Workspace-relative source paths; MCP reads disk and builds the payload. |
+| 2                 | `semanticDiffPath` | Pre-built payload file already on disk (CI artifacts, offline dumps).                   |
+| 3                 | `semanticDiff`     | Tiny one-file smoke payloads.                                                           |
+
+## Why `files[]` is best practice
+
+| Layer                      | `files[]`               | Inline `semanticDiff`                                  |
+| -------------------------- | ----------------------- | ------------------------------------------------------ |
+| Agent / MCP tool-call JSON | Path list only          | Full source in args (burns IDE context + chat history) |
+| Critic LLM                 | Full source (MCP-built) | Full source (same)                                     |
+
+`files[]` does **not** reduce Critic tokens. It stops the IDE agent from re-serializing every file into the tool call.
+
+Limits (SSoT: `SEMANTIC_DIFF_SOURCE_FILES` in `src/constants.ts`):
+
+- Max **10** paths per call
+- Max **1 MiB** per file
+- Max **5 MiB** total
+
+Paths must be **relative to `VIBE_WORKSPACE_ROOT`**. Absolute paths and `..` traversal are rejected.
+
+## Example (preferred)
+
+```json
+{
+  "phaseId": "phase-6-§1a",
+  "report": "…",
+  "files": ["features/compliance/constants.ts", "packages/compliance/src/export-zip.ts"],
+  "round": 1
+}
+```
+
+## `semanticDiffPath` (optional)
+
+Write the same FILE:…CONTENT: string to a UTF-8 file under the workspace (raw text or JSON `{"semanticDiff":"..."}`), then pass the relative path. Size ≤ 5 MiB (`SEMANTIC_DIFF_FILE.MAX_BYTES`).
+
+## Inline `semanticDiff`
+
+Same FILE:…CONTENT: string as the tool argument. Prefer `files[]`.
+
+## Payload format (what the Critic sees)
+
+```
+FILE: packages/shared/src/result.ts
+CONTENT:
+[FULL FILE CONTENT]
+
+FILE: packages/shared/src/domain-error.ts
+CONTENT:
+[FULL FILE CONTENT]
+```
+
+Markers are SSoT: `SEMANTIC_DIFF_PAYLOAD_MARKERS` in `src/constants.ts`.
+
+## Soft advisory
+
+If any FILE block exceeds `SEMANTIC_DIFF_FILE.SOFT_WARN_LINES_PER_FILE_BLOCK` (default 500), responses may include `semanticDiffHints` (non-blocking).
+
+## Status updates on ACCEPT
+
+By default ACCEPT writes `.vibe/status.json`. Skip pollution for probes:
+
+- `updateStatus: false`, or
+- `phaseId` starting with `mcp-smoke-` / `vibe-gate-probe-` (`PHASE_STATUS_POLICY`)
+
+## Workspace root (multi-repo / public)
+
+Set **`VIBE_WORKSPACE_ROOT`** to the **consumer project** root (Cursor: `${workspaceFolder}` in **project** `.cursor/mcp.json`). Do **not** hardcode a single repo path in user-level MCP config — that breaks other projects.
+
+See `examples/cursor-mcp.project.json` and [INSTALLATION.md](INSTALLATION.md).

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,62 @@
+# Troubleshooting
+
+## Common Issues
+
+### "No LLM provider available"
+
+**Cause:** Missing API key or wrong `CRITIC_PROVIDER`.
+
+**Fix:**
+
+1. Set the correct API key for your provider: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `MINIMAX_API_KEY`, or `OPENCODE_API_KEY`.
+2. Ensure `CRITIC_PROVIDER` matches one of: `openai`, `anthropic`, `google`, `minimax`, `opencode`.
+3. Verify `.env` is loaded (MCP config must pass `env` or the process must inherit it).
+
+### MCP server not connecting
+
+**Cause:** Wrong `cwd`, missing build/dependencies, or env not passed.
+
+**Fix:**
+
+1. Use `npx -y vibe-gate-mcp`, or an absolute `node dist/index.mjs` path while developing.
+2. Ensure `npm run build` completes from the project root.
+3. Pass API keys in `env` in the MCP config.
+
+### Status and Roadmap out of sync
+
+**Cause:** Phase completed without using `submit_phase_review`, or manual edits.
+
+**Fix:** Manually update `.vibe/status.json` to match the completed phase.
+
+### Wrong workspace root (monorepo)
+
+**Cause:** MCP runs from monorepo root; project is in a subdirectory.
+
+**Fix:** Set `VIBE_WORKSPACE_ROOT=/path/to/subproject` in env (project `.cursor/mcp.json` → `${workspaceFolder}`).
+
+### IDE shows empty `submit_phase_review` properties / missing `files`
+
+**Cause:** The running MCP process has not been restarted after a build, or the tool input schema is not exposed as a plain object — MCP SDK then advertises `properties: {}`.
+
+**Fix:**
+
+1. Run `npm run build` in the package directory.
+2. **Toggle/restart** the vibe-gate MCP server in the IDE after rebuilding. Reload the IDE if necessary.
+3. Confirm tool description mentions `files` and properties include `files`, `semanticDiffPath`, `semanticDiff`.
+4. The server registers `submitPhaseReviewFieldsSchema` (plain object) for ListTools.
+
+### `files` / `semanticDiffPath` file not found
+
+**Cause:** `VIBE_WORKSPACE_ROOT` points at the wrong repo (often hardcoded in **user-level** MCP), or path is absolute / outside the workspace.
+
+**Fix:** Set `VIBE_WORKSPACE_ROOT` only in **project** `.cursor/mcp.json` → `${workspaceFolder}`. Paths must be relative to that root. Remove hardcoded consumer paths from user-level MCP.
+
+### Debug logging
+
+**Cause:** Need to see parse/read failures.
+
+**Fix:** Set `DEBUG=1` in env. Logs go to stderr.
+
+## References
+
+- [docs/project/VARIABLES.md](project/VARIABLES.md) — Env reference

package/docs/USAGE.md

@@ -0,0 +1,125 @@
+# Usage Guide
+
+## First Run
+
+1. Ensure `.env` and MCP config are set (see [INSTALLATION.md](INSTALLATION.md)).
+2. Restart your IDE or Cursor so it picks up the MCP server.
+3. Create `.vibe/` in your project root (or let the tool create it).
+
+## Project Setup
+
+### rules.json (optional)
+
+Define hard and soft rules for the Critic:
+
+```json
+{
+  "hardRules": [{ "id": "SEC-1", "description": "No hardcoded secrets", "category": "security" }],
+  "softRules": [{ "id": "STYLE-1", "description": "Prefer named exports", "category": "style" }]
+}
+```
+
+### DEBT.md (optional)
+
+Created automatically when the Critic issues a DEBT verdict and the Implementer accepts:
+
+```
+## Records
+
+### YYYY-MM-DD - Duplicate subject
+
+- **Phase:** example-phase
+- **Rationale:** ...
+- **Status:** Open
+```
+
+## Configuration & API Keys
+
+Vibe-Gate requires an AI provider API key. You can place your configuration (`API_KEY`, `CRITIC_PROVIDER`, `CRITIC_MODEL`, `CRITIC_PERSONA`, etc.) in **any** of the following locations:
+
+1. **Your Project's `.env` (Recommended for Monorepos/Projects):**
+   Simply place a `.env` file in the root of the project you are working on (the one defined by `VIBE_WORKSPACE_ROOT`). Vibe-Gate will automatically read it.
+2. **MCP Config (`mcpServers.vibe-gate.env`):**
+   Add it directly to your IDE's MCP settings. Variables here overwrite any `.env` files.
+3. **Package-local `.env` (local development):**
+   Copy `.env.example` to `.env` in the package directory, or set the same keys in MCP `env`.
+
+> **Tip:** You can mix and match. For example, define `CRITIC_PROVIDER` broadly in the MCP config, but set a specific `OPENAI_API_KEY` inside your current project's `.env` file.
+
+### OpenAI (default)
+
+```env
+CRITIC_PROVIDER=openai
+OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+# CRITIC_MODEL=gpt-5.4  # optional, default
+```
+
+### Anthropic
+
+```env
+CRITIC_PROVIDER=anthropic
+ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
+# CRITIC_MODEL=claude-4.6-sonnet  # optional
+```
+
+### Google Gemini
+
+```env
+CRITIC_PROVIDER=google
+GOOGLE_GENERATIVE_AI_API_KEY=YOUR_GOOGLE_API_KEY
+# CRITIC_MODEL=gemini-3.1-pro  # optional
+```
+
+### MiniMax
+
+```env
+CRITIC_PROVIDER=minimax
+MINIMAX_API_KEY=...
+# CRITIC_MODEL=MiniMax-M3  # default; also: MiniMax-M2.7, MiniMax-M2.5
+```
+
+MiniMax uses an Anthropic-compatible API endpoint. Default model: `MiniMax-M3`. Also available: `MiniMax-M2.7`, `MiniMax-M2.5`, and high-speed variants.
+
+### OpenCode (Zen or Go)
+
+```env
+CRITIC_PROVIDER=opencode
+OPENCODE_API_KEY=...
+OPENCODE_PLAN=go
+# CRITIC_MODEL=minimax-m3
+```
+
+OpenCode has two plans sharing the same API key from [opencode.ai/auth](https://opencode.ai/auth):
+
+| Plan                    | `OPENCODE_PLAN` | Base URL                        | Billing              |
+| ----------------------- | --------------- | ------------------------------- | -------------------- |
+| **Go** (subscription)   | `go`            | `https://opencode.ai/zen/go/v1` | Monthly subscription |
+| **Zen** (pay-as-you-go) | `zen`           | `https://opencode.ai/zen/v1`    | Per-token credits    |
+
+**Important:** On Go, `minimax-m3` uses the Anthropic `/messages` endpoint (not chat completions). On Zen, it uses `/chat/completions`.
+
+Model IDs are lowercase (`minimax-m3`). Display names like `MiniMax-M3` are accepted as aliases.
+
+For the **direct MiniMax provider** (`CRITIC_PROVIDER=minimax`), use PascalCase: `MiniMax-M3`.
+
+### Personas
+
+```env
+CRITIC_PERSONA=security-first   # or performance-freak, clean-code-monk
+```
+
+## MCP Tools
+
+| Tool                  | Purpose                                              |
+| --------------------- | ---------------------------------------------------- |
+| `submit_phase_review` | Implementer reports phase completion; Critic reviews |
+| `log_human_decision`  | Judge records decision on deadlock                   |
+
+`submit_phase_review` — **prefer `files[]`** (workspace-relative source paths; MCP builds FILE:…CONTENT:). Alternatives: `semanticDiffPath` or inline `semanticDiff` — exactly one. Use `updateStatus: false` for probes. See [SEMANTIC_DIFF_PAYLOAD.md](SEMANTIC_DIFF_PAYLOAD.md).
+
+See [docs/project/api/mcp-tools.md](project/api/mcp-tools.md) for full API docs.
+
+## References
+
+- [docs/VIBE-GATE.md](VIBE-GATE.md) — Purpose and flow
+- [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) — Common issues

package/docs/VIBE-GATE.md

@@ -0,0 +1,66 @@
+# Vibe-Gate: Purpose and Features
+
+## Purpose
+
+Vibe-Gate is a **Model Context Protocol (MCP)** server designed for developers who write code with AI-assisted IDEs (Cursor, Windsurf, Antigravity, etc.) using a "vibe coding" workflow — rapid iteration with minimal friction.
+
+**Core problem:** When coding quickly with AI, security, architectural consistency, and long-term maintainability often get deprioritized. Reviewing entire codebases with another AI is expensive and hits context limits.
+
+**Solution:** Vibe-Gate acts as an **Adversarial Quality Gate**. The IDE AI (Implementer) reports what it changed; a separate Critic AI reviews only the changed artifacts and side effects. The two models debate; the human (Judge) steps in only when they deadlock.
+
+## Features
+
+### 1. Three-Actor Model & Multi-Model Support
+
+To prevent "echo chambers," the Critic should ideally be a different LLM than the Implementer. Vibe-Gate is LLM-agnostic, allowing you to configure the Critic with your preferred flagship model (e.g., Gemini 3.1 Pro, Claude 4.6 Sonnet, GPT-5.4) via standard API keys.
+
+| Role            | Actor            | Responsibility                                                                |
+| --------------- | ---------------- | ----------------------------------------------------------------------------- |
+| **Implementer** | IDE AI           | Writes code, triggers the `submit_phase_review` MCP tool at phase completion. |
+| **Critic**      | Vibe-Gate MCP AI | Reviews reports against rules, challenges violations.                         |
+| **Judge**       | Human            | Resolves deadlocks; decisions feed project-specific learning.                 |
+
+### 2. Roadmap Tracking & Phase Execution
+
+Vibe-Gate tracks project progress via a local `.vibe/status.json` or `ROADMAP.md` file. It monitors the debate rounds (e.g., `count: x`) for each sub-phase. A phase is only marked as complete after a successful resolution between the AIs or a direct Judge override.
+
+### 3. Rule System
+
+- **Hard Rules:** Non-negotiable. Security (injection, secrets), core architecture, data integrity. No exceptions.
+- **Soft Rules:** Deferrable. Style, refactoring, performance. If the Implementer objects, items are logged to `DEBT.md` instead of blocking.
+
+### 4. Conflict Loop (Max 3 Rounds)
+
+1. **Round 1:** Implementer reports → Critic responds with risks and gaps.
+2. **Rounds 2–3:** Implementer fixes or argues (e.g., "Soft rule, log to debt").
+3. **Deadlock:** If no agreement after 3 rounds → Conflict Alert → Judge decides.
+
+### 5. Smart Context (Cost Control)
+
+Vibe-Gate does not send full codebases to the Critic. It sends targeted payloads:
+
+- **Project Blueprint:** Framework conventions (e.g., Nuxt 3 structures, Node.js workers, WebSocket handling).
+- **Semantic Diff:** Logical changes and structural side effects.
+- **Dependency List:** New packages (analyzed for bundle bloat and known CVEs).
+- **Critical Snippets:** Only high-risk areas like Auth, DB schemas, or API endpoints.
+
+### 6. Personas
+
+The Critic can run in different modes (configurable):
+
+- **Security First:** Strict on security, token leaks, and compliance.
+- **Performance Freak:** Focus on latency, memory leaks, and bundle size.
+- **Clean Code Monk:** Focus on readability, DRY principles, and maintainability.
+
+### 7. Project-Local Learning
+
+Judge decisions are written to a `preferences.log` file in the workspace. The Critic reads this on subsequent runs to align with the Judge’s specific coding style. Learning is strictly per-project (no automatic cross-project sharing).
+
+---
+
+## Language Policy (npm Publish)
+
+- **No duplicate content** — single source, no TR/EN split.
+- **Published files:** English only (`README.md`, `package.json`, `rules.json`, `docs/`, `.env.example`).
+- **All project files:** English only. No TR/EN split.
+- **Vibe-Gate output in user projects:** Always English.

package/docs/project/VARIABLES.md

@@ -0,0 +1,50 @@
+# Environment Variables
+
+Copy [`.env.example`](../../.env.example) → `.env` in the package directory **or** set the same keys in MCP `env`. Without a Critic key, `submit_phase_review` cannot run.
+
+## Required (pick one provider)
+
+| Variable                       | When required                  | Description                                                    |
+| ------------------------------ | ------------------------------ | -------------------------------------------------------------- |
+| `CRITIC_PROVIDER`              | Recommended (default `openai`) | `openai` \| `anthropic` \| `google` \| `minimax` \| `opencode` |
+| `OPENAI_API_KEY`               | `CRITIC_PROVIDER=openai`       | OpenAI API key                                                 |
+| `ANTHROPIC_API_KEY`            | `CRITIC_PROVIDER=anthropic`    | Anthropic API key                                              |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | `CRITIC_PROVIDER=google`       | Google Gemini API key                                          |
+| `MINIMAX_API_KEY`              | `CRITIC_PROVIDER=minimax`      | MiniMax API key                                                |
+| `OPENCODE_API_KEY`             | `CRITIC_PROVIDER=opencode`     | From https://opencode.ai/auth                                  |
+
+## Optional
+
+| Variable              | Default                   | Description                                                               |
+| --------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `VIBE_WORKSPACE_ROOT` | auto (`cwd` package root) | **Consumer project root.** In Cursor set `${workspaceFolder}` in mcp.json |
+| `CRITIC_MODEL`        | provider default          | Model id override                                                         |
+| `CRITIC_PERSONA`      | `clean-code-monk`         | `security-first` \| `performance-freak` \| `clean-code-monk`              |
+| `OPENCODE_PLAN`       | `go`                      | `go` (subscription) or `zen` (pay-as-you-go)                              |
+| `DEBUG`               | unset                     | Log parse/read failures to stderr                                         |
+
+## Priority
+
+1. Process / MCP `env` block
+2. `VIBE_WORKSPACE_ROOT/.env` (consumer)
+3. Package-local `.env` (local development)
+
+## Cursor example
+
+```json
+{
+  "mcpServers": {
+    "vibe-gate": {
+      "command": "npx",
+      "args": ["-y", "vibe-gate-mcp"],
+      "env": {
+        "VIBE_WORKSPACE_ROOT": "${workspaceFolder}",
+        "CRITIC_PROVIDER": "openai",
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+**SEC-002:** Never commit real keys. Prefer local `.env` over committing secrets into mcp.json when possible.

package/docs/project/api/mcp-tools.md

@@ -0,0 +1,115 @@
+# MCP Tools API
+
+Vibe-Gate exposes tools via MCP (Model Context Protocol). No HTTP API.
+
+---
+
+## submit_phase_review
+
+**Purpose:** Implementer (IDE AI) submits phase completion report for Critic review.
+
+**Handler:** `handleSubmitPhaseReview` (`src/tools/submit-phase-review.ts`)
+
+### Data Flow
+
+```
+MCP Client → tools/call submit_phase_review
+    ↓
+args: { phaseId, report, files | semanticDiffPath | semanticDiff, updateStatus?, ... }
+    ↓
+exactly one payload source:
+  files[] → buildSemanticDiffFromSourceFiles (read each path under VIBE_WORKSPACE_ROOT)
+  semanticDiffPath → loadSemanticDiffFromWorkspacePath
+  semanticDiff → use inline string
+    ↓
+parseSemanticDiff() → filesChanged count / context
+    ↓
+buildContextBlock() → blueprint, deps, FILE:…CONTENT: corpus
+    ↓
+provider.complete([system, user]) → Critic LLM
+    ↓
+parseVerdictFromResponse → ACCEPT | REJECT | …
+    ↓
+if ACCEPT && shouldPersistPhaseStatus(phaseId, updateStatus) → updatePhaseOnAccept → .vibe/status.json
+    ↓
+Response JSON: { verdict, model, usage, statusUpdated, statusSkipped?, statusError?, … }
+```
+
+### Input Schema
+
+| Field            | Type     | Required | Description                                                                                    |
+| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------- |
+| phaseId          | string   | yes      | Phase identifier (e.g. `phase-6-§1a`)                                                          |
+| report           | string   | yes      | Implementer report                                                                             |
+| files            | string[] | xor†     | **Preferred.** Workspace-relative source paths; MCP builds FILE:…CONTENT:. Max 10.             |
+| semanticDiffPath | string   | xor†     | Pre-built payload file under `VIBE_WORKSPACE_ROOT` (raw or JSON `{"semanticDiff":"..."}`).     |
+| semanticDiff     | string   | xor†     | Inline FILE:…CONTENT: payload (not git diff).                                                  |
+| updateStatus     | boolean  | no       | `false` skips status.json on ACCEPT. Default skips `mcp-smoke-` / `vibe-gate-probe-` prefixes. |
+| dependencies     | string[] | no       | New/updated packages                                                                           |
+| round            | number   | no       | Round (1–3), default 1                                                                         |
+| logToDebt        | object   | no       | When DEBT: `{ subject, rationale }`                                                            |
+
+† **Exactly one** of `files` (non-empty), `semanticDiffPath` (non-empty), or `semanticDiff` (non-empty). See [SEMANTIC_DIFF_PAYLOAD.md](../../SEMANTIC_DIFF_PAYLOAD.md).
+
+**ListTools note:** MCP registers `submitPhaseReviewFieldsSchema` (plain ZodObject). Exactly-one rules run in the handler via `submitPhaseReviewInputSchema`.
+
+### Output
+
+```json
+{
+  "verdict": "ACCEPT | REJECT | BLOCK | DEBT | CONCERNS_ADDRESSED | LOW_QUALITY | INSUFFICIENT_REVIEW",
+  "model": "gpt-5.4",
+  "usage": { "promptTokens": 0, "completionTokens": 0 },
+  "statusUpdated": true,
+  "statusSkipped": false,
+  "statusError": "optional, when ACCEPT but status write failed"
+}
+```
+
+- `statusUpdated`: `true` when verdict is ACCEPT and `.vibe/status.json` was updated.
+- `statusSkipped`: `true` when ACCEPT but status write was skipped (probe policy / `updateStatus: false`).
+- `statusError`: Present when ACCEPT but status update failed (e.g., permission denied).
+- `semanticDiffHints` (optional): Soft advisory when a FILE block exceeds line threshold.
+
+File-load errors return `{ error, code? }` (e.g. `PATH_OUTSIDE_WORKSPACE`, `FILE_TOO_LARGE`, `TOO_MANY_FILES`, `JSON_SCHEMA`, `REALPATH_FAILED`).
+
+---
+
+## log_human_decision
+
+**Purpose:** Judge (human) records decision on deadlock; appends to `.vibe/preferences.log`.
+
+### Data Flow
+
+```
+MCP Client → tools/call log_human_decision
+    ↓
+args: { caseId, decision, rationale?, confirmationToken? }
+    ↓
+if VIBE_HUMAN_CONFIRMATION_TOKEN set → require matching confirmationToken
+    ↓
+mkdir(.vibe) if needed
+    ↓
+append new entry → writeFile(preferences.log)
+    ↓
+Response: { success, path, message } | { success:false, code: HUMAN_CONFIRMATION_REQUIRED }
+```
+
+### Input Schema
+
+| Field             | Type   | Required | Description                                                                           |
+| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
+| caseId            | string | yes      | Conflict case identifier                                                              |
+| decision          | string | yes      | ACCEPT_IMPLEMENTER \| ACCEPT_CRITIC \| CUSTOM                                         |
+| rationale         | string | no       | Optional rationale                                                                    |
+| confirmationToken | string | when env | Required when `VIBE_HUMAN_CONFIRMATION_TOKEN` is set (blocks implementer self-unlock) |
+
+### Structured ≠ prose
+
+`submit_phase_review` may return `code: STRUCTURED_PROSE_MISMATCH`. Resolve by **another Critic round** (`submit_phase_review`) — not `ACCEPT_IMPLEMENTER`, not a human. Mid-loop `ACCEPT_IMPLEMENTER` returns `CONTINUE_CRITIC_DEBATE`.
+
+### Output
+
+```json
+{ "success": true, "path": ".vibe/preferences.log", "message": "Decision logged to preferences.log" }
+```

package/examples/cursor-mcp.project.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "vibe-gate": {
+      "command": "npx",
+      "args": ["-y", "vibe-gate-mcp"],
+      "env": {
+        "VIBE_WORKSPACE_ROOT": "${workspaceFolder}",
+        "CRITIC_PROVIDER": "openai",
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
+      }
+    }
+  }
+}

package/examples/cursor-mcp.user-local-dev.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "vibe-gate": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/vibe-gate-mcp/dist/index.mjs"],
+      "cwd": "/ABSOLUTE/PATH/TO/vibe-gate-mcp",
+      "env": {
+        "VIBE_WORKSPACE_ROOT": "${workspaceFolder}",
+        "CRITIC_PROVIDER": "opencode",
+        "CRITIC_MODEL": "minimax-m3",
+        "OPENCODE_API_KEY": "YOUR_OPENCODE_API_KEY",
+        "OPENCODE_PLAN": "go"
+      }
+    }
+  }
+}