revdeck 0.0.0-stage → 0.2.0

package/docs/adr/0001-daemon-first.md

@@ -0,0 +1,64 @@
+# ADR-0001: Daemon-first architecture
+
+[English](0001-daemon-first.md) | [Русский](../ru/adr/0001-daemon-first.md)
+
+- **Status:** Accepted
+- **Date:** 2026-11-11
+
+## Context
+
+The first version of revdeck ran as a process that a human started manually on the host
+(`node devtools/mr-ui/server.mjs <N>`), and the agent communicated with it through `.revdeck/*.json`
+files. This gave the right security boundary (the agent does not publish, and the token stays on the
+host), but:
+
+- the server died with the terminal, and the link had to be copied manually;
+- file exchange caused races (file version, 409) and required syncing fields between the agent and
+  the UI;
+- it was impossible to have several reviews at once;
+- each project required its own copy of the script and ran in one process.
+
+What was needed: launch from a `/` command in any harness, a full-featured interface, several reviews,
+GitLab and GitHub, configurable project rules, and installation into any agent project.
+
+## Decision
+
+We build the product around a [local daemon](../architecture.md):
+
+- the `revdeck daemon` — a long-lived process owned by the user that holds credentials, SQLite,
+  providers, RPC, HTTP/SSE, and the UI;
+- the CLI and MCP are thin clients over RPC; the MCP server contains no review logic;
+- the agent writes only drafts; publication requires an approval tied to the plan hash;
+- the UI is a Svelte SPA served by the daemon and outlives the agent session;
+- state lives in SQLite under `~/.local/state/revdeck`, not in JSON in the repository;
+- the file format remains as `export`/`import` for compatibility and for sandboxes without a socket.
+
+## Alternatives considered
+
+1. **An MCP process per session, without a daemon.** Simpler installation, but the UI does not survive
+   the session, several agents compete for state, the token ends up in the process that the agent
+   launches, and the container scenario still requires a separate process on the host. Rejected.
+2. **File exchange only.** Maximum compatibility, but races and manual startup remain. Kept as
+   `export/import`, not as the primary path.
+3. **A cloud service.** Removes installation, but requires sending code and tokens outside. Contradicts
+   the "local, one person" requirement.
+
+## Consequences
+
+- A daemon lifecycle appears: socket, pid, logs, autostart (`daemon install`), handling of a stale
+  socket. The client can start the daemon itself.
+- Socket permissions are part of the security model: directory 0700, socket 0600.
+- In a container, either a mounted socket or `REVDECK_URL`/`REVDECK_TOKEN` is needed; otherwise, use
+  `export`/`import` and run on the host. `revdeck devcontainer --write` generates the socket/state
+  mounts and marks the container with `REVDECK_DEV_CONTAINER=1`, so it never starts its own daemon.
+- One daemon serves several repositories: `root` is passed on `open`, and the config is read from that
+  root.
+- Client and daemon versions must match; [`PROTOCOL_VERSION`](../protocol.md) was added.
+- This creates room for background sync and SSE, which improves UX compared to manually refreshing
+  the page.
+
+## Follow-up decisions
+
+- Native drafts (GitLab draft notes, GitHub pending review) are the next step; the provider interface
+  already contains `capabilities.nativeDrafts`.
+- A multi-user mode is not planned; if needed, a separate ADR.

package/docs/architecture.md

@@ -0,0 +1,92 @@
+# Architecture
+
+[English](architecture.md) | [Русский](ru/architecture.md)
+
+## Goals
+
+1. The agent receives review context and project rules deterministically, without manual files and
+   without access to platform tokens.
+2. Publishing to GitLab/GitHub happens only after human approval and is idempotent.
+3. One tool works in any harness: MCP for agent clients, the CLI as the universal layer, and a web UI
+   for humans.
+4. Project rules are [configured](configuration.md), not hardcoded in the prompt.
+
+## Non-goals
+
+- Replacing GitLab/GitHub's native diff viewer. The UI is optimized for triage and approval.
+- Built-in static analysis. Checks are delegated to the project's linter, types, and tests.
+- A multi-user server. The model is one user, several reviews, and a
+  [daemon on the host](adr/0001-daemon-first.md).
+
+## Components
+
+```text
+agent (MCP/CLI) ──▶ revdeck daemon ──glab/gh──▶ GitLab/GitHub
+                         │
+                   SQLite + UI ◀── human
+```
+
+- `src/core` — pure functions and models: unified diff parser, rules, finding fingerprints,
+  [publication sanitizer](threat-model.md), secret redaction, safe process execution.
+- `src/providers` — the only place that knows about platforms. `Provider` normalizes MR/PR, diff,
+  threads, replies, resolution, and comment creation.
+- `src/daemon/service.ts` — orchestrator: review refresh, drafts, decisions, publication plan,
+  approval, idempotent writes, background sync.
+- `src/daemon/store.ts` — SQLite (`node:sqlite`): reviews, diff/thread snapshot, drafts, findings,
+  decisions, comments, approvals, audit.
+- `src/daemon/rpc.ts` — [JSON-RPC](protocol.md) over a Unix socket (0600) for the CLI and MCP.
+- `src/daemon/http.ts` — UI and `/api/*`, SSE events, cookie session with a one-time token.
+- `src/cli` — commands, `init`, `doctor`, export/import of the old file format.
+- `src/mcp` — MCP server: tools and prompts, a thin wrapper over RPC.
+- `ui` — Svelte 5 SPA, built into `dist/ui`.
+
+## Data flow
+
+1. `revdeck open 42` → RPC `reviews.open` with the working copy `root`.
+2. The daemon determines the platform/host/project (arguments → config → git remote), creates a
+   provider, reads the MR, diff, and threads, and saves a snapshot and synthetic drafts.
+3. The agent requests `revdeck_context`: the daemon assembles effective rules (documents and sections
+   for changed paths), snippets, threads, and findings.
+4. The agent writes drafts (`drafts.put`, `findings.put`, `summary.put`, `notes.update`).
+5. A human in the UI calls `publish.preview` → sees the exact plan and hash → `publish.approve` →
+   `publish.commit`. The daemon executes only the items included in the approved plan.
+6. Background sync every 2 minutes refreshes open reviews and broadcasts SSE events to the UI.
+
+## Data model
+
+- `ReviewRef` — platform, host, project, number. `reviewId` — `platform:host/project!number`.
+- `DiffFile`/`Hunk`/`DiffLine` — line numbers in the old and new versions; a finding's `line` always
+  refers to the new file.
+- `Thread`/`Note` — shared discussion model.
+- `Finding` — a review finding with `id`, `fingerprint`, severity, file/line, text, and status
+  (`draft`, `accepted`, `rejected`, `published`, `fixed`, `stale`).
+- `Approval` — a one-time id tied to `hash = sha256(canonicalJson({reviewId, kind, items}))`,
+  with a 10-minute TTL.
+
+## Idempotency and concurrency
+
+- Draft and finding writes go through a single process; SQLite in WAL mode.
+- Publication marks the approval as used before execution. Items that have already been posted
+  (matching `posted`, `published`) are skipped. A failure of one item does not cancel the others and
+  is recorded in the draft/finding.
+- The plan hash protects against agent edits between the moment the plan is shown to the human and
+  publication: text changed → hash mismatch → approval rejected.
+- `findings.put` — replaces the set while preserving `id` and decision; findings that disappear are
+  marked `stale` rather than deleted.
+
+## Extension
+
+- **New platform**: implement `Provider` and add a branch in `createProvider`; nothing else changes.
+- **New harness**: `revdeck init --adapters <name>` writes the MCP config or command file and links the
+  canonical `.agents/skills/revdeck` skill.
+  Harnesses without MCP use the CLI.
+- **Rules**: `rules.map`/`rules.sources` in `.revdeck.yml`; rule packs can be distributed as a regular
+  configuration file.
+- **Checks**: `checks` with argv, no shell; run only on explicit confirmation.
+
+## Performance
+
+- The diff is parsed on the server; the UI receives files as a list and hunks one file at a time.
+- Review state does not contain the full diff; SSE reports changes and the UI refetches the state.
+- Snippets for threads and findings are computed on the server and size-limited.
+- Rule context is capped at 320 KB; MCP context is capped by the `max_bytes` parameter.

package/docs/configuration.md

@@ -0,0 +1,123 @@
+# Configuration
+
+[English](configuration.md) | [Русский](ru/configuration.md)
+
+Configuration lives in the `.revdeck.yml` (or `.revdeck.yaml`) file at the repository root. The schema
+is validated with zod; an unknown field produces an error with the field path.
+
+```yaml
+version: 1
+provider:
+  type: auto            # auto | gitlab | github
+  host: gitlab.example.com
+  project: group/project
+  base: develop
+output:
+  language: auto        # auto | ru | en — language of findings and replies
+rules:
+  sources: [AGENTS.md]
+  map:
+    - match: ["src/**", "lib/**"]
+      docs: ["docs/Architecture.md", "docs/Styleguide.md#Базовый стиль"]
+      note: "application code"
+  ignore: ["**/generated/**"]
+checks:
+  - id: lint
+    name: ESLint
+    argv: [npm, run, lint]
+    when: ["src/**"]
+    consent: true
+    timeoutMs: 300000
+publish:
+  requireApproval: true
+  maxComments: 50
+```
+
+## provider
+
+| Field | Default | Meaning |
+|---|---|---|
+| `type` | `auto` | `auto` — inferred from the git remote; otherwise an explicit platform |
+| `host` | from the remote | host without a scheme |
+| `project` | from the remote | GitLab `group/project`, GitHub `owner/repo` |
+| `base` | `develop`/`main` | base for the local diff |
+
+Explicit CLI arguments (`--platform`, `--project`, `--host`) take precedence over the config, and the
+config takes precedence over the git remote. This way, tampering with `.git/config` cannot redirect the
+review to a different project.
+
+## output
+
+- `language: auto` — findings and replies are written in the language of the MR description and
+  discussions; if there is no text, English is used. `ru`/`en` pin the language explicitly.
+- The language of the rules and documents does not depend on this: the agent reads them as they are and
+  quotes them verbatim.
+- This is the language of the **review output**, not of the CLI/UI interface. The interface is switched
+  via `--lang ru|en`, `REVDECK_LANG`, or the toggle in the UI.
+- `revdeck init --lang en` selects the English skill and writes `REVDECK_LANG` to the MCP config.
+
+## rules
+
+- `sources` — the default documents when none of the `map` rows match. Empty — auto-discovery
+  (`AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `docs/ARCHITECTURE.md`, `docs/Architecture.md`,
+  `docs/STYLEGUIDE.md`, `docs/Styleguide.md`, `docs/CONTRIBUTING.md`).
+- `map` — a list of rules: `match` (a glob or an array of globs) and `docs` (an array of selectors).
+  Multiple matching rows are merged.
+- `ignore` — glob exclusions: a matching file is left out of rule analysis.
+
+### Document selectors
+
+| Selector | What is included |
+|---|---|
+| `docs/Architecture.md` | the entire document |
+| `docs/Styleguide.md#Базовый стиль` | the section for the heading (that level and below, up to the next heading of the same level) |
+| `docs/File.md#L10-L25` | a line range |
+| `docs/File.md#10-25` | the same range |
+
+A heading is normalized: case, whitespace, and punctuation do not matter. `#Слои и зависимости` and
+`#layers` are different sections, while `#Слои-и-зависимости` and `#Слои и зависимости` are the same
+section. If a section is not found, revdeck emits a warning and does not fall back to the whole document.
+
+### Glob
+
+`*` matches within one segment, `**` matches any depth, `?` matches one character, `{a,b}` is an
+alternative. Examples: `src/**/*.ts`, `docs/{guides,adr}/**`, `**/*.test.ts`.
+
+## checks
+
+Checks are argv arrays, not shell strings. This matters: the config lives in the repository, and a shell
+string would allow arbitrary code to be executed during a review.
+
+| Field | Meaning |
+|---|---|
+| `id` | stable identifier |
+| `name` | display name |
+| `argv` | command and arguments; the executable comes first |
+| `when` | glob paths: run only if the diff touched them; empty — always |
+| `consent` | requires explicit confirmation (default `true`) |
+| `timeoutMs` | timeout (default 300,000) |
+
+Running: `revdeck checks <N> --run --yes`. The MCP tool only shows the plan.
+
+## publish
+
+- `requireApproval` — kept for backward compatibility; approval is always required when publishing is
+  done by a non-interactive process.
+- `maxComments` — maximum number of comments per plan (1–200).
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `REVDECK_STATE_DIR` | state directory (default `~/.local/state/revdeck`) |
+| `REVDECK_RUNTIME_DIR` | socket directory (default `$XDG_RUNTIME_DIR/revdeck`) |
+| `REVDECK_URL` + `REVDECK_TOKEN` | connect to the daemon over HTTP (container/port forwarding) |
+| `REVDECK_DEV_CONTAINER=1` | do not start a local daemon; fail with a host-daemon hint instead |
+| `REVDECK_UI_HOST` | host used by `revdeck ui` from a container (for example `host.docker.internal`) |
+| `REVDECK_ROOT` | project root for the MCP server |
+| `REVDECK_LANG` | CLI/MCP/daemon language: `ru` or `en` (default: system locale) |
+
+## Validation
+
+`revdeck config --json` shows the effective config, the path where it was found, and warnings.
+`revdeck rules --explain src/app.ts` shows which documents and sections were selected for the file.

package/docs/integrations.md

@@ -0,0 +1,123 @@
+# Harness integrations
+
+[English](integrations.md) | [Русский](ru/integrations.md)
+
+revdeck has two portable layers and one adapter layer:
+
+- **MCP** (stdio) — the `revdeck_*` tools work in any MCP-capable client.
+- **CLI** — the same capabilities without MCP: `revdeck open/context/findings/reply/publish`.
+- **`/` command** — each harness has its own; `revdeck init` creates the right file.
+
+A full integration = MCP + skill (procedures) + command (entry point). Without MCP, the CLI and
+skill remain: the agent calls commands through the shell.
+
+## Matrix
+
+| Harness | `/` command | What `init` writes |
+|---|---|---|
+| Claude Code | `/revdeck` | `.claude/commands/revdeck.md`, `.claude/skills/revdeck` → `../../.agents/skills/revdeck`, `.mcp.json` |
+| Cursor | `/revdeck` | `.cursor/commands/revdeck.md`, `.cursor/mcp.json` |
+| Codex CLI | prompt `revdeck` | `.codex/prompts/revdeck.md`; MCP in `~/.codex/config.toml` (manually) |
+| Gemini CLI | `/revdeck` | `.gemini/commands/revdeck.toml`; MCP in the Gemini settings (manually) |
+| OpenCode | `/revdeck` | `.opencode/command/revdeck.md` |
+| GitHub Copilot | prompt file | `.github/prompts/revdeck.prompt.md` |
+| DSH | plugin (see below) | `.agents/skills/revdeck/*` (including `agents/openai.yaml`) + YAML snippet in the output |
+| Universal | — | `.agents/skills/revdeck/*` (including `agents/openai.yaml`) + MCP |
+
+Comment attachments are uploaded by the host daemon. GitLab uses project uploads and returns an
+absolute URL; GitHub has no public attachment API, so the editor asks for a URL instead.
+
+`revdeck init --adapters dsh,claude` explicitly enables the adapters you need. A repeated `init`
+does not overwrite existing command files and does not clobber other keys in `.mcp.json`.
+
+The skill has one canonical copy: `.agents/skills/revdeck` (including `agents/openai.yaml` for OpenAI
+harnesses). Harnesses that keep skills under their own directory get a link to it — `.claude/skills/revdeck`
+is a symlink to `../../.agents/skills/revdeck`, with a copy fallback on Windows and on filesystems without
+symlink support. Old copies created by an earlier `init` are replaced when they still carry
+`name: revdeck`.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "revdeck": {
+      "command": "npx",
+      "args": ["-y", "revdeck", "mcp"],
+      "env": { "REVDECK_LANG": "en" }
+    }
+  }
+}
+```
+
+`init` writes `npx -y revdeck mcp` into the MCP config. Publishing over MCP
+requires an `approval_id`: a human issues it in the UI or in the CLI with `--yes`, and the agent
+cannot obtain it.
+
+## DSH
+
+The DSH MCP client is configured in the Cordis profile:
+
+```yaml
+- id: mcp-revdeck
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: revdeck
+    transport: stdio
+    command: npx
+    args: ['-y', 'revdeck', 'mcp']
+    env:
+      REVDECK_LANG: en
+```
+
+The tools will appear as `mcp__revdeck__*`. DSH does not support MCP prompt templates, so `/revdeck`
+requires a host command (`ctx.commands.register`) or a client action — that is a separate wrapper
+plugin. Until then, use the skill + MCP tools: the `/` slash is not required for things to work.
+
+## Container and devcontainer
+
+The daemon, `glab` and `gh` stay on the host; the container only needs the revdeck CLI or MCP server.
+Generate the devcontainer settings from the repository root:
+
+```bash
+revdeck devcontainer          # print the mounts and environment
+revdeck devcontainer --write  # merge them into .devcontainer/devcontainer.json
+```
+
+`--write` mounts the host runtime and state directories at fixed paths and sets:
+
+```json
+{
+  "REVDECK_RUNTIME_DIR": "/run/revdeck",
+  "REVDECK_STATE_DIR": "/var/lib/revdeck",
+  "REVDECK_DEV_CONTAINER": "1",
+  "REVDECK_UI_HOST": "host.docker.internal"
+}
+```
+
+The runtime directory is mounted read-write (the socket lives there), the state directory is
+read-only (the client reads `daemon.json` with the token). Existing mounts, environment variables and
+`runArgs` are preserved; only the two revdeck mounts and the `REVDECK_*` keys are managed.
+
+After rebuilding the container, start the daemon on the host (`revdeck daemon start`). Inside the
+container `revdeck` never starts its own daemon: if the socket is unreachable it fails with a
+`DEVCONTAINER` error and a hint. `revdeck doctor` does not look for `glab`/`gh` in the container.
+
+The container user must be able to connect to the host socket (normally the same UID; the socket is
+0600). To open the UI from the container, start the host daemon with `revdeck daemon start --host
+0.0.0.0` and use `host.docker.internal`; otherwise open the UI on the host.
+
+Fallbacks:
+
+1. `REVDECK_URL=http://host.docker.internal:<port>` and `REVDECK_TOKEN=<token>` — the HTTP transport,
+   with the daemon started on the host with `--host 0.0.0.0`.
+2. `revdeck export <N>` on the host and `revdeck import <N>` in the container — a file bridge.
+
+## Verification
+
+```bash
+revdeck doctor
+```
+
+Shows the binaries found, `glab`/`gh` authorization, daemon status and the installed adapter. In a
+devcontainer it checks the host daemon instead of looking for `glab`/`gh` inside.

package/docs/protocol.md

@@ -0,0 +1,102 @@
+# Protocol
+
+[English](protocol.md) | [Русский](ru/protocol.md)
+
+## Transports
+
+1. **Unix socket** (primary): `$XDG_RUNTIME_DIR/revdeck/daemon.sock`, directory 0700, socket 0600.
+   JSON lines, one request/response per line.
+2. **HTTP**: `POST /api/rpc` on loopback with a cookie session. Needed for containers where the socket
+   is not forwarded (`REVDECK_URL` + `REVDECK_TOKEN`).
+3. **UI HTTP**: `/api/*` and SSE `/api/events` for the browser.
+
+## Messages
+
+Request:
+
+```json
+{"id": 1, "method": "reviews.get", "params": {"review": "gitlab:gitlab.com/group/project!42"}}
+```
+
+Response:
+
+```json
+{"id": 1, "result": {"review": {"id": "...", "info": {}, "threads": []}}}
+```
+
+Error:
+
+```json
+{"id": 1, "error": {"message": "...", "code": "APPROVAL", "hint": "..."}}
+```
+
+`id` is a number. A connection is considered untrusted until the first successful request:
+authorization is enforced by the socket file's permissions.
+
+## Methods
+
+| Method | Parameters | Result |
+|---|---|---|
+| `ping` | — | version, protocol, pid |
+| `reviews.list` | — | saved reviews |
+| `reviews.remoteList` | `root`, `scope`, `limit` | open reviews from the platform |
+| `reviews.open` | `root`, `input`/`platform`/`project`/`host`/`branch` | review snapshot |
+| `reviews.refresh` | `review` | refreshed snapshot |
+| `reviews.get` | `review`, `refresh?` | snapshot (without the full diff) |
+| `diff.get` | `review`, `file` | file hunks |
+| `drafts.put` | `review`, `threadId`, `patch` | draft |
+| `findings.put` | `review`, `findings[]` | findings after merge |
+| `findings.list` | `review` | findings |
+| `summary.put` | `review`, `summary` | summary |
+| `decisions.put` | `review`, `decisions` | human decisions |
+| `notes.add` | `review`, `file`, `line`, `text`, `toAgent` | line comment |
+| `notes.update` | `review`, `noteId`, `patch` | updated comment |
+| `reactions.list` | `review`, `noteIds[]` | reactions grouped by comment id |
+| `reactions.toggle` | `review`, `noteId`, `emoji` | `active`, fresh reactions |
+| `attachments.upload` | `review`, `name`, `contentType`, `data` (base64) | `name`, absolute `url`, `markdown` |
+| `notes.delete` | `review`, `noteId` | `{ok}` |
+| `publish.preview` | `review`, `kind`, `ids[]` | plan + warnings |
+| `publish.approve` | `review`, `kind`, `ids[]`, `hash` | `approvalId`, `expiresAt` |
+| `publish.commit` | `review`, `approvalId` | per-item results |
+| `rules.get` | `review` | rules markdown, checks, warnings |
+| `checks.run` | `review`, `allowRun`, `ids[]` | check results |
+| `audit.tail` | `limit` | latest actions |
+
+## Approval
+
+1. `publish.preview` builds `items` — the exact bodies, paths, lines, and resolve flags — and
+   `hash = sha256(canonicalJson({reviewId, kind, items}))`.
+2. The human sees the plan. `publish.approve` recomputes the plan from the same `ids`; if the hash does
+   not match, it returns an error. Otherwise it creates a one-time `approval_id` with a 10-minute TTL.
+3. `publish.commit` verifies that the approval has not been used and has not expired, marks it as used,
+   and executes only `items`. Items that have already been posted are skipped.
+
+The agent cannot call `publish.approve`: the MCP tool does not expose it. A human confirms in the UI or
+in the CLI with `--yes`.
+
+## HTTP API (UI)
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/` | SPA; `?t=<token>` sets the cookie and redirects |
+| GET | `/assets/*` | static build assets |
+| GET | `/api/health` | liveness |
+| GET | `/api/reviews` | review list |
+| GET | `/api/state?review=` | snapshot for the UI |
+| GET | `/api/diff?review=&file=` | file hunks |
+| GET | `/api/rules?review=` | rules |
+| GET | `/api/events` | SSE: `review` |
+| POST | `/api/reviews/open`, `/api/reviews/refresh` | open/refresh |
+| POST | `/api/drafts`, `/api/findings`, `/api/summary`, `/api/decisions` | drafts |
+| POST | `/api/notes` | `action: add/update/delete` |
+| GET | `/api/reactions?review=&notes=` | reactions for comment ids |
+| POST | `/api/reactions` | toggle a reaction |
+| POST | `/api/attachments` | upload an image/video and return an absolute link |
+| POST | `/api/publish/preview`, `/approve`, `/commit` | publishing |
+| POST | `/api/checks` | checks |
+| POST | `/api/rpc` | RPC proxy for the HTTP transport |
+
+## Versioning
+
+`PROTOCOL_VERSION` in `src/version.ts` is checked during the handshake; the client and daemon must be
+the same package version. A method mismatch returns `METHOD` with a hint to update revdeck.

package/docs/ru/README.md

@@ -0,0 +1,17 @@
+# Документация revdeck
+
+[English](../README.md) | Русский
+
+Английская документация в `docs/` — каноническая; русские переводы лежат рядом в `docs/ru/` и могут
+немного отставать.
+
+| Документ | Английский | Русский |
+|---|---|---|
+| Архитектура | [../architecture.md](../architecture.md) | [architecture.md](architecture.md) |
+| Конфигурация и правила | [../configuration.md](../configuration.md) | [configuration.md](configuration.md) |
+| Протокол RPC и HTTP | [../protocol.md](../protocol.md) | [protocol.md](protocol.md) |
+| Модель угроз | [../threat-model.md](../threat-model.md) | [threat-model.md](threat-model.md) |
+| Интеграции с харнессами | [../integrations.md](../integrations.md) | [integrations.md](integrations.md) |
+| ADR-0001: демон-first | [../adr/0001-daemon-first.md](../adr/0001-daemon-first.md) | [adr/0001-daemon-first.md](adr/0001-daemon-first.md) |
+
+Начните с [README](../../README.ru.md): установка, команды и настройка MCP.

package/docs/ru/adr/0001-daemon-first.md

@@ -0,0 +1,62 @@
+# ADR-0001: Демон-first архитектура
+
+[English](../../adr/0001-daemon-first.md) | Русский
+
+- **Статус:** Accepted
+- **Дата:** 2026-11-11
+
+## Контекст
+
+Первая версия revdeck работала как процесс, который человек запускал вручную на хосте
+(`node devtools/mr-ui/server.mjs <N>`), а агент общался с ним через файлы `.revdeck/*.json`.
+Это давало правильную границу безопасности (агент не публикует, токен остаётся на хосте), но:
+
+- сервер умирал вместе с терминалом, ссылку нужно было копировать вручную;
+- файловый обмен давал гонки (версия файла, 409) и требовал синхронизации полей между агентом и UI;
+- нельзя было держать несколько ревью одновременно;
+- каждый проект требовал своей копии скрипта и шёл в одном процессе.
+
+Нужны: запуск по `/`-команде в любом харнессе, полноценный интерфейс, несколько ревью, GitLab и
+GitHub, конфигурируемые правила проекта и установка в любой агентский проект.
+
+## Решение
+
+Строим продукт вокруг локального демона:
+
+- демон `revdeck daemon` — долгоживущий процесс пользователя, держит креды, SQLite, провайдеры, RPC,
+  HTTP/SSE и UI;
+- CLI и MCP — тонкие клиенты к RPC; MCP-сервер не содержит логики ревью;
+- агент пишет только черновики; публикация требует approval, привязанного к хешу плана;
+- UI — Svelte SPA, отдаётся демоном, живёт дольше сессии агента;
+- состояние — SQLite в `~/.local/state/revdeck`, а не JSON в репозитории;
+- файловый формат остаётся как `export`/`import` для совместимости и песочниц без сокета.
+
+## Рассмотренные альтернативы
+
+1. **MCP-процесс на сессию, без демона.** Проще установка, но UI не переживает сессию, несколько
+   агентов конкурируют за состояние, токен оказывается в процессе, который запускает агент, и
+   контейнерный сценарий всё равно требует отдельного процесса на хосте. Отклонено.
+2. **Только файловый обмен.** Максимальная совместимость, но гонки и ручной запуск остаются.
+   Оставлено как `export/import`, не как основной путь.
+3. **Облачный сервис.** Снимает установку, но требует передавать код и токены наружу. Противоречит
+   требованию «локально, один человек».
+
+## Последствия
+
+- Появляется жизненный цикл демона: сокет, pid, логи, автозапуск (`daemon install`), обработка
+  зависшего сокета. Клиент умеет поднять демон сам.
+- Права на сокет — часть модели безопасности: каталог 0700, сокет 0600.
+- В контейнере нужен либо смонтированный сокет, либо `REVDECK_URL`/`REVDECK_TOKEN`; иначе —
+  `export`/`import` и запуск на хосте. `revdeck devcontainer --write` генерирует mounts сокета и
+  state и ставит `REVDECK_DEV_CONTAINER=1`, поэтому контейнер не запускает свой демон.
+- Один демон обслуживает несколько репозиториев: `root` передаётся при `open`, конфиг читается из
+  этого корня.
+- Версии клиента и демона должны совпадать; добавлен `PROTOCOL_VERSION`.
+- Появляется место для фонового sync и SSE, что улучшает UX по сравнению с ручным обновлением
+  страницы.
+
+## Последующие решения
+
+- Native drafts (GitLab draft notes, GitHub pending review) — следующий шаг; интерфейс провайдера
+  уже содержит `capabilities.nativeDrafts`.
+- Многопользовательский режим не планируется; при необходимости — отдельный ADR.