ADRs
Overview

Architecture Decision Records для ARNO проекта.

Назначение

ADR — формальный артефакт major architectural decisions. Каждый ADR fixates:

  • Context — почему решение нужно сейчас
  • Decision — что выбрали
  • Consequences — последствия (плюсы, минусы, trade-offs)
  • Alternatives — что отвергли и почему

Per Rules.md §governance: major architecture changes требуют ADR перед изменением master spec.

Когда создавать ADR

Triggers:

  • Vendor migration (Liveblocks → self-hosted Yjs, Cloudflare → AWS, etc.)
  • Replace core dependency (Auth.js → Lucia, react-flow → alternative)
  • Switch backend/frontend runtime
  • Microservice extraction из monolith
  • Major schema redesign
  • Crypto algorithm changes (§0.5)
  • New architectural principle добавить в §0.3

NOT triggers (minor):

  • Refactoring within module
  • Library version bumps
  • Bug fixes
  • New endpoints в existing API contract

Naming convention

NNNN-short-title-lowercase.md где NNNN — 4-digit sequential (0001-, 0002-, ...).

Template

См. README.md — full ADR template + process.

Active ADRs

{/* AUTOGEN:adr-index START */}

Auto-generated by scripts/gen-adr-index.ts on 2026-05-24. Do not edit by hand — regenerate via pnpm docs:adr-index.

Core ARNO

#TitleStatusDatePhase / Feature
0001Static export now, edge adapter when Auth/API landAccepted2026-05-200 → 8
0002Module-level stores + useSyncExternalStoreAccepted2026-05-202 → 7
0003Design-system source: local snapshot → GitHub APIAccepted (replaces interim local snapshot)2026-05-205
0004Render adapter postMessage protocolAccepted (v1)2026-05-206 → 7
0005Dedicated Worker для API, не Pages FunctionsAccepted2026-05-218
0006Backend-driven GitHub OAuth, не Auth.js на PagesAccepted2026-05-219

Feature: URL-import

#TitleStatusDatePhase / Feature
0007URL-import: code-first, не vision-firstAccepted2026-05-22URL-import (unparks §V "Small-company path / ARNO Studio")
0008Hybrid stack: schema-driven priority chains + reactive visionAccepted2026-05-22URL-import
0009Acceptance gate: 3 эмпирических bool, не weighted scoresAccepted2026-05-22URL-import
0010Completeness: матрица combinations, не point checkAccepted2026-05-22URL-import
0011Vision activation: reactive, не predictiveAccepted2026-05-22URL-import
0012Uniqueness: user decides, не algorithmAccepted2026-05-22URL-import
0013"Чем дольше живём — тем меньше платим" как hard requirementAccepted2026-05-22URL-import
0014Legal-clean distillation: Qwen teacher, не Anthropic/OpenAIAccepted2026-05-22URL-import (data flywheel — ADR 0013)
0015Explicit non-use of Claude API в URL-import stackAccepted2026-05-22URL-import
0016V1 staging area вместо direct git commitAccepted2026-05-22URL-import
0017Shadow data: ToS-based disclosure, не registration checkboxAccepted2026-05-22URL-import (data flywheel — ADR 0013)
0018Atom embeddings: E5-small text, не DINOv2 visualAccepted2026-05-22URL-import (atoms — cache L3)

{/* AUTOGEN:adr-index END */}

Lifecycle

  • Proposed → drafted, не reviewed
  • Accepted → reviewed, applied к master spec
  • Deprecated → no longer relevant но preserved для history
  • Superseded by ADR-XXXX → replaced by newer decision

ADRs никогда не удаляются — history immutable. Status changes reflect evolution.

Связь с master spec

После acceptance ADR:

  1. Master spec _index.md updated (version bump, changelog entry с ADR reference)
  2. Affected sections rewritten
  3. Parking list updated если applicable
  4. ADR remains canonical "почему" для решения; master spec — canonical "что" сейчас
API referenceADR 001 — Static export now, edge adapter when Auth/API land