docs: make documentation checks self-contained

2026-09-15 20:45:40 +03:00
parent c557af4ea5
commit 97069d6f6d
25 changed files with 125 additions and 112 deletions
@@ -1,6 +0,0 @@
 {
  "main": "2567a755569e6ef6ba12063b62f202fe52884ce7",
  "frontend": "0244acf429c525b23117f165bbe52ef5403eefd3",
  "backend": "660b250ecd05e38784690b9a9adb381764c0ca7c",
  "specs": "9e227a563dda67620f0ad78228aa8a4c18bf35a0"
 }
@@ -8,39 +8,13 @@ on:
 jobs:
  verify:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: workspace/docs
    steps:
      - uses: https://github.com/actions/checkout@v4
-        with:
+      - name: Record checked revision
-          path: workspace/docs
+        run: git rev-parse HEAD
      - name: Checkout compatible peer revisions
        env:
          SOURCE_BRANCH: ${{ github.head_ref || github.ref_name }}
          TARGET_BRANCH: ${{ github.base_ref || github.ref_name }}
        run: |
          set -eu
          for repo in main frontend backend specs; do
            ref=develop
            case "$SOURCE_BRANCH:$TARGET_BRANCH" in
              release/*:*|*:main)
                ref=$(jq -er --arg repo "$repo" '.[$repo]' .ci/refs.json)
                printf '%s\n' "$ref" | grep -Eq '^[0-9a-f]{40}$'
                ;;
            esac
            target="../$repo"
            if [ "$repo" = main ]; then target=..; fi
            git init "$target"
            git -C "$target" remote add origin "https://git.personal.ksv741.ru/WealthLedger/$repo.git"
            git -C "$target" fetch --depth 1 origin "$ref"
            git -C "$target" checkout --detach FETCH_HEAD
            git -C "$target" rev-parse HEAD
          done
          git rev-parse HEAD
      - uses: https://github.com/actions/setup-node@v4
        with:
-          node-version-file: workspace/docs/.nvmrc
+          node-version-file: .nvmrc
      - run: npm ci
      - name: Check Markdown and relative links
        run: npm run verify
@@ -4,8 +4,10 @@
 затем только затронутую тему. Docs объясняет систему; требования принадлежат
 основным спецификациям, реализация и coding conventions — соседним репозиториям.
-Проверь существенные факты адресно по спецификациям, ADR и реализации с учётом
+Проверь существенные факты по локальным тематическим страницам и ADR;
-веток и незакоммиченных изменений. Расхождение обозначь, не выбирая источник
+внешние источники используй как справочные свидетельства, когда они доступны.
 Недостающие факты отмечай явно; инструкции и проверки не требуют других checkout.
 Расхождение обозначь, не выбирая источник
 победителем автоматически. Перенос сохраняет полезное содержание и входящие
 ссылки. Docs описывает текущее устройство системы; история поставок остаётся в Git.
 Отчёты аудитов и исследований в docs не размещаются. Подтверждённые решения
@@ -19,6 +21,6 @@
 ## Ветки и релизы
 Работа — в отдельной ветке от `develop`, затем PR в `develop`; в `main` напрямую
-не пушить. Release/hotfix и синхронизация веток — по [root README](../README.md#релизы-и-ветки).
+не пушить. Release/hotfix и синхронизация веток — по [README](README.md#релизы).
 Commits и заголовки PR — Conventional Commits; для спецификаций допустим `spec:`.
-Перед подготовкой релиза прочитай root README; версии вручную не повышать.
+Перед подготовкой релиза прочитай местный README; версии вручную не повышать.
@@ -8,13 +8,13 @@ Docs даёт самостоятельное понимание продукта
 | Вид знания | Где поддерживается |
 | --- | --- |
-| Согласованное проверяемое поведение: требования и сценарии | [Основные спецификации](../specs/AI_INDEX.md) в `specs/openspec/specs/` |
+| Согласованное проверяемое поведение: требования и сценарии | [Основные спецификации](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/AI_INDEX.md) в `specs/openspec/specs/` |
 | Предложения изменений, их проектирование и задачи | OpenSpec changes в существующем Store `wealth-ledger-specs`, `specs/openspec/changes/` |
 | Понимание системы, областей и взаимодействий | Тематические страницы docs |
 | Принятые решения и подтверждённые причины | Единственный журнал [docs/adr](adr/README.md) |
 | Конкретная реализация и технические контракты | Код, тесты, схемы, конфигурация; публичный OpenAPI формирует backend |
 | Размещение кода, conventions, команды разработки и проверки | Локальные инструкции frontend/backend |
-| Выбор репозитория и типа знания | Корневой [AGENTS](../AGENTS.md) |
+| Работа над docs | Локальные [AGENTS](AGENTS.md) и этот документ |
 История аудитов и проверок остаётся в Git, Issues и PR. `CHANGELOG.md`
 генерируется release-it из commits; вручную дублировать его на тематических страницах не нужно.
@@ -86,9 +86,11 @@ Docs объясняет смысл контракта, не вводя неза
 Нужные точные значения сопровождай определяющим источником, чтобы не создать
 конкурирующую норму. Паспорта страниц, Evidence-секции и номера строк не требуются.
-Внутри docs используем относительные Markdown-ссылки. Между репозиториями —
+Внутри docs используем относительные Markdown-ссылки. Внешние репозитории —
-относительный путь через соседний корень, например `../specs/AI_INDEX.md` из README.
+необязательные справочные веб-ссылки на опубликованный источник. Основной текст
-Проверяй регистр, файл и якорь в фактическом workspace. Перенос требует исправить
+и инструкции должны быть понятны без открытия этих ссылок. Проверяй локальные
 файлы/якоря; для удалённых источников не обещай проверку их доступности CI.
 Перенос требует исправить
 входящие ссылки активных Markdown-документов; исторические архивы и dated audits
 сохраняют адреса своего времени. Короткий указатель оставляем только при реальной
 необходимости совместимости, без второй копии содержания.
@@ -153,8 +155,7 @@ npm run verify
 Существующий gate запускает Markdown lint с проверкой относительных ссылок
 и якорей, затем `git diff --check`. Он охватывает новые Markdown-файлы;
 обычный diff их не показывает, поэтому отдельно просмотри untracked-содержание.
-При изменениях соседних репозиториев выполни там `git diff --check` и проверь
+Markdown-only правки не требуют тестов приложения или соседнего checkout.
 затронутые ссылки. Markdown-only правки не требуют тестов всего приложения.
 Правило relative-links не проверяет внешние URL и HTML-ссылки. Mermaid-рендер
 в gate не входит; используй доступный локальный рендерер без отправки материалов
@@ -169,13 +170,10 @@ npm run verify
 ### CI и обновления зависимостей
 `.gitea/workflows/verify.yml` запускает этот gate на push и PR с Node
-из `.nvmrc` и установкой через `npm ci`. Checkout docs размещается внутри
+из `.nvmrc` и установкой через `npm ci`. Скачивается только docs;
-workspace из `WealthLedger/main`, рядом с frontend, backend и specs. Соседние
+его SHA сохраняется в логе. Ошибка checkout, Markdown или внутренней ссылки
-репозитории для разработки берутся из `develop`; для `main`, PR в `main`
+завершает job с FAIL. Внешние веб-ссылки — справочные; CI не проверяет их
-и `release/*` — из полных SHA в `.ci/refs.json`. SHA всех пяти участников
+доступность, Mermaid-render или semantic correctness.
 сохраняются в логе.
 Ошибка checkout, Markdown или относительной ссылки завершает job с FAIL.
 Это проверка ссылок на выбранные revisions, без Mermaid-render и semantic review.
 `security.yml` при push, PR и ежедневно проверяет всю Git-историю через
 Gitleaks 8.30.1 с redacted-выводом и все npm dependencies через
@@ -187,4 +185,4 @@ Renovate объединяет minor/patch updates; major требует согл
 Dependency Dashboard, automerge не включён. Required checks включаются
 отдельно в Gitea; workflow сам по себе не запрещает merge.
-Версии и ветки: [процесс релиза](../README.md#релизы-и-ветки).
+Версии и ветки: [процесс релиза](README.md#релизы).
@@ -50,12 +50,12 @@ WealthLedger помогает частному инвестору понимат
 ## Границы знаний
-[Основные спецификации](../specs/AI_INDEX.md) сохраняют согласованное проверяемое
+[Основные спецификации](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/AI_INDEX.md) сохраняют согласованное проверяемое
 поведение, а OpenSpec changes — предложения, дизайн и задачи изменений.
 Фактический Store находится в `specs/openspec/`, основные требования — в
 `specs/openspec/specs/`. Docs объясняет систему; код, тесты, схемы и конфигурация
 задают конкретный механизм, а [ADR](adr/README.md) сохраняют принятые решения.
-Локальные инструкции [frontend](../frontend/AGENTS.md) и [backend](../backend/AGENTS.md)
+Локальные инструкции [frontend](https://git.personal.ksv741.ru/WealthLedger/frontend/src/commit/9f7e342333b80bfacfd5bc394a2dcd0613d33ff3/AGENTS.md) и [backend](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/AGENTS.md)
 описывают изменение реализации и её проверки.
 Эти источники дополняют друг друга. Найденный незавершённый change не доказывает
@@ -67,3 +67,39 @@ WealthLedger помогает частному инвестору понимат
 Правила изменения текста, диаграмм, ссылок и проверки docs-impact находятся
 в [CONTRIBUTING](CONTRIBUTING.md).
 ## Релизы
 Репозиторий выпускается независимо. `develop` — интеграция, `main` — принятые
 релизы. Работа: `codex/<task>` от актуального `develop`, PR в `develop`.
 Обычные PR допускают squash; release и обратная синхронизация сохраняют историю.
 Commits и PR titles — Conventional Commits, включая `spec:`. Версии вручную не повышай.
 1. Получи `main`, `develop` и теги: `git fetch origin --tags`. Убедись, что
   `develop` содержит последний релиз. Создай `release/<name>` от проверенного
   `develop`; `nvm use --silent`, `npm ci`. Hotfix начинается от `main` в
   `release/hotfix-<name>` и проходит тот же процесс.
 2. На чистой ветке выполни `npm run release:preview`, просмотри версию/changelog,
   затем `npm run release:prepare`. Команда создаёт `chore(release): X.Y.Z`,
   обновляет manifest/lockfile/CHANGELOG; тег и push не выполняет. Не обходи
   guards ветки, чистого дерева, отсутствующих тегов или уже подготовленной версии.
 3. Проверь diff и штатные gates этого репозитория. Отправь только release-ветку,
   открой PR в `main` с заголовком `chore(release): X.Y.Z`. После зелёных
   `verify`, `security`, `commits` выполни fast-forward-only merge. Если `main`
   изменился, согласуй историю и повтори проверки кандидата.
 4. Получи удалённый `main`, сравни его HEAD с проверенным release SHA и версией
   manifest/lockfile. Создай аннотированный `vX.Y.Z` именно на этом SHA:
   `git tag -a vX.Y.Z <release-sha> -m "Release X.Y.Z"`, затем отправь только
   `git push origin refs/tags/vX.Y.Z`. Не запускай release-it повторно на `main`.
 5. Верни release-коммит через PR `main → develop` без squash/rebase; проверь,
   что `develop` содержит тег. Опубликованные теги не перемещай. При сбое после
   merge создай отсутствующий тег без нового bump; до merge исправь и проверь
   существующий кандидат без повторного повышения версии.
 `feat:` повышает minor, `fix:`/`perf:` и прочие разрешённые типы — patch;
 `!`/`BREAKING CHANGE:` — major, включая версии до 1.0. `chore(release):`
 исключён из рекомендации и changelog. Конфигурация — `.release-it.json`.
 В Gitea для `main`/`develop` должны быть запрещены прямой/force push и обход
 администратором, обязательны `verify`, `security`, `commits`; теги `v*` защищены.
 Workflow сам не включает эти настройки. Отдельное review approval для одного
 владельца не требуется. Npm publishing, deploy и Gitea Releases не включены.
@@ -65,8 +65,8 @@ Client Cached Snapshot прежнего подключения больше не
 Пользовательский сценарий описан в [интеграции T-Bank](../../integrations/tbank.md).
 Согласованные правила frontend находятся в workspace-спецификациях
-[query coherence](../../../specs/openspec/specs/frontend-query-coherence/spec.md)
+[query coherence](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-query-coherence/spec.md)
-и [data resilience](../../../specs/openspec/specs/frontend-data-resilience/spec.md);
+и [data resilience](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-data-resilience/spec.md);
 серверные правила — в
-[portfolio](../../../specs/openspec/specs/portfolio-view/spec.md) и
+[portfolio](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md) и
-[ledger](../../../specs/openspec/specs/brokerage-account-ledger/spec.md).
+[ledger](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-ledger/spec.md).
@@ -44,6 +44,6 @@ actions. Устаревший серверный Portfolio Snapshot показы
 [аутентификации](../../domains/authentication/overview.md).
 Согласованное поведение раскрыто в workspace-спецификациях
-[UI resilience](../../../specs/openspec/specs/frontend-ui-resilience/spec.md),
+[UI resilience](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-ui-resilience/spec.md),
-[loading presentation](../../../specs/openspec/specs/frontend-loading-presentation/spec.md)
+[loading presentation](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-loading-presentation/spec.md)
-и [data resilience](../../../specs/openspec/specs/frontend-data-resilience/spec.md).
+и [data resilience](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-data-resilience/spec.md).
@@ -8,6 +8,15 @@ Backend генерирует OpenAPI из собственного публич
 схемы находятся вне frontend. Это разделение принято в
 [ADR 002](../adr/002-nest-generated-openapi-contract.md) и
 [ADR 014](../adr/014-trusted-openapi-input.md).
 Backend командой `npm run openapi:generate` создаёт `openapi.json` без запуска
 сервера и не хранит результат в Git. Contract test сравнивает вывод генератора
 с Nest runtime schema настроенного приложения. Frontend хранит полученный
 artifact у себя и проверяет соответствие generated types этой копии. CI не
 скачивает соседние репозитории и не сравнивает их текущие revisions. Обновление
 входного artifact потребителя выполняется отдельно с review; совместимость
 развёрнутых версий не доказывается одним зелёным локальным CI.
 API имеет prefix `/api/v1`; Swagger публикуется для локальной разработки по
 environment policy, а не используется frontend в runtime.
@@ -36,7 +45,7 @@ message/stack. Типичный ответ:
 HTTP-ответа после всех стадий обработки запроса.
 **Известное расхождение:** согласованная
-[спецификация аутентификации](../../specs/openspec/specs/user-authentication/spec.md#requirement-стандартные-ответы-об-ошибках)
+[спецификация аутентификации](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/user-authentication/spec.md#requirement-стандартные-ответы-об-ошибках)
 требует `pointer` и `detail` для невалидных полей. В текущей конфигурации
 валидация формирует строковые сообщения, а фильтр ожидает структурированные
 ошибки полей; поэтому корректность деталей `errors` не подтверждена.
@@ -74,5 +83,5 @@ client request ID. Это позволяет сопоставить публич
 Выбор logger и граница ответственности описаны в
 [ADR 008](../adr/008-pino-backend-logging.md); согласованное поведение — в
 workspace-спецификации
-[Structured logging](../../specs/openspec/specs/backend-structured-logging/spec.md).
+[Structured logging](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/backend-structured-logging/spec.md).
 Сборщик, срок хранения журналов и alerting не определяются приложением.
@@ -44,4 +44,4 @@
 и [банковских картах](../domains/cards/overview.md).
 Согласованная общая основа описана в
-[спецификации дизайн-системы](../../specs/openspec/specs/frontend-design-system/spec.md).
+[спецификации дизайн-системы](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-design-system/spec.md).
@@ -93,7 +93,7 @@ sequenceDiagram
 [журнал операций](../operations/overview.md) или историю закрытых счетов.
 Для совокупного результата доступен [режим «Все счета»](../portfolio/all-accounts.md).
-Согласованное поведение описывает [спецификация счетов](../../../specs/openspec/specs/brokerage-accounts/spec.md).
+Согласованное поведение описывает [спецификация счетов](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-accounts/spec.md).
 Её раздел об экране пока требует одноколоночного списка и не описывает
 счётчики акций и облигаций. Текущая реализация и её проверки используют
 две колонки на широком экране и показывают эти счётчики. Расхождение требует
@@ -23,7 +23,7 @@
 Access token действует 15 минут и хранится только в памяти браузера.
 Refresh token имеет серверный срок 7 дней, заменяется при восстановлении
 сессии и передаётся в cookie `refresh_token` с `httpOnly` и `SameSite=Lax`.
-Сроки определены в [спецификации сессий](../../../specs/openspec/specs/user-authentication/spec.md#requirement-access-и-refresh-сессии)
+Сроки определены в [спецификации сессий](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/user-authentication/spec.md#requirement-access-и-refresh-сессии)
 и [ADR 006](../../adr/006-auth-session-policy.md).
 После перезагрузки SPA получает новый access token через refresh-cookie.
@@ -117,6 +117,6 @@ Backend проверяет учётные данные и tokens, хранит
 и проверку атомарности с реальной изолированной базой.
 Согласованное поведение находится в workspace-спецификации
-[User authentication](../../../specs/openspec/specs/user-authentication/spec.md).
+[User authentication](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/user-authentication/spec.md).
 Правила начального ожидания — в
 [состояниях интерфейса](../../architecture/cross-cutting/ui-resilience.md).
@@ -140,6 +140,6 @@ JavaScript Number. Отдельный ввод ограничен signed64: на
 сохраняет новую финансовую историю и при откате приложения. Устройство хранения
 описано в [контейнерах](../../architecture/containers.md#хранимые-данные-и-границы-доступа).
 Согласованный контракт банковского учёта находится в
-[manual-bank-cards](../../../specs/openspec/changes/add-manual-bank-cards/specs/manual-bank-cards/spec.md).
+[manual-bank-cards](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/changes/add-manual-bank-cards/specs/manual-bank-cards/spec.md).
 Автоматическая загрузка банковских данных, кредитные карты, другие валюты,
 бюджеты и общий баланс банковских денег с инвестициями в эту версию не входят.
@@ -59,7 +59,7 @@
 для полного месяца это предыдущий полный месяц, иначе — непосредственно
 предшествующий интервал той же включительной длительности. Текущая страница
 его не показывает. Это расходится с
-[основным требованием сравнений](../../../specs/openspec/specs/brokerage-account-income-analytics/spec.md#requirement-period-comparisons-preserve-calendar-and-currency-meaning),
+[основным требованием сравнений](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-income-analytics/spec.md#requirement-period-comparisons-preserve-calendar-and-currency-meaning),
 которое описывает оба сравнения. Требуется отдельно согласовать этот разрыв;
 здесь сохранено различие между ответом API и фактическим экраном.
@@ -104,7 +104,7 @@ Frontend проверяет принадлежность выплат по по
 Аналитика только читает данные, не хранит историю операций и не рассчитывает налоги, инвестиционную эффективность, доходность, валютную конвертацию или общий мультивалютный итог.
-Основное проверяемое поведение — в [спецификации дохода](../../../specs/openspec/specs/brokerage-account-income-analytics/spec.md),
+Основное проверяемое поведение — в [спецификации дохода](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-income-analytics/spec.md),
 точная форма ответа — в [HTTP API](../../architecture/http-api.md).
 Не следует использовать календарь будущих событий для восстановления
 состава уже полученного дохода.
@@ -29,7 +29,7 @@
 Суммы рассчитаны по количеству на `calculatedAt`. Они не учитывают будущие
 сделки, право владения на дату реестра и персональный налоговый расчёт.
 Есть неразрешённое ограничение интерпретации:
-[основная спецификация](../../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-forecasts-preserve-event-meaning-and-uncertainty)
+[основная спецификация](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-forecasts-preserve-event-meaning-and-uncertainty)
 и текущая подсказка экрана называют прогноз суммой «до налогов», но для
 дивиденда реализация только умножает `dividend_net` на количество.
 Налоговый смысл этого поля не подтверждён локальными материалами; на
@@ -61,7 +61,7 @@ API принимает необязательные `from` и `to` в форма
 Итоги остаются в ответе API; полный экран показывает список без общего итога.
 Текущие controller, сервис и экран поддерживают выбор периода, тогда как
-[основная спецификация](../../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-account-page-presents-an-upcoming-events-list)
+[основная спецификация](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-account-page-presents-an-upcoming-events-list)
 описывает фиксированные 30 дней и экран без фильтров. Документация отражает
 реализованный выбор периода, не изменяя это несогласованное требование.
@@ -132,13 +132,13 @@ HTML-источник, общий кэш и поведение при измен
 выход очищает кэш сессии. Общие график, позиция и личные события
 имеют общее представление на страницах акций и облигаций.
-Основные спецификации [портфеля](../../../specs/openspec/specs/portfolio-view/spec.md)
+Основные спецификации [портфеля](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md)
-и [журнала](../../../specs/openspec/specs/brokerage-account-ledger/spec.md)
+и [журнала](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-ledger/spec.md)
 описывают исходные финансовые понятия. Отдельная основная спецификация
 страницы облигации в текущем OpenSpec Store не найдена; условия вычислений
-подтверждены [каталогом](../../../backend/src/modules/investments/instruments/bonds/application/bond-catalog.service.ts),
+подтверждены [каталогом](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/bonds/application/bond-catalog.service.ts),
-[рыночными данными](../../../backend/src/modules/investments/instruments/bonds/application/bond-market.service.ts),
+[рыночными данными](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/bonds/application/bond-market.service.ts),
-[выплатами](../../../backend/src/modules/investments/instruments/bonds/application/bond-income.service.ts)
+[выплатами](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/bonds/application/bond-income.service.ts)
-и [проверками](../../../backend/src/modules/investments/instruments/bonds/application/bond.spec.ts).
+и [проверками](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/bonds/application/bond.spec.ts).
 Границы источников описаны в [разделе интеграций](../../integrations/README.md),
 сходное разделение рыночных и личных данных — в [акциях](stocks.md).
@@ -169,11 +169,11 @@ TTM означает последние 12 месяцев, MRQ — послед
 История открытых счетов не обещает полную историю владения, включая закрытые
 счета, переводы и универсальные корпоративные события.
-Основные спецификации [портфеля](../../../specs/openspec/specs/portfolio-view/spec.md)
+Основные спецификации [портфеля](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md)
-и [журнала](../../../specs/openspec/specs/brokerage-account-ledger/spec.md)
+и [журнала](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-ledger/spec.md)
 задают исходные финансовые понятия. Отдельная основная спецификация страницы
 акции в текущем OpenSpec Store не найдена; описанные механизмы проверяются
-по [каталогу](../../../backend/src/modules/investments/instruments/stocks/application/stock-catalog.service.ts),
+по [каталогу](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/stocks/application/stock-catalog.service.ts),
-[рыночным данным](../../../backend/src/modules/investments/instruments/stocks/application/stock-market.service.ts),
+[рыночным данным](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/stocks/application/stock-market.service.ts),
-[выплатам](../../../backend/src/modules/investments/instruments/stocks/application/stock-income.service.ts) и [проверкам](../../../backend/src/modules/investments/instruments/stocks/application/stock.spec.ts).
+[выплатам](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/stocks/application/stock-income.service.ts) и [проверкам](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/instruments/stocks/application/stock.spec.ts).
 Сопоставление с облигациями — на [странице облигаций](bonds.md).
@@ -112,6 +112,6 @@ Backend хранит не более 100 страниц в памяти проц
 и `TBANK_UNAVAILABLE` сохраняют [общую семантику API](../../architecture/http-api.md).
 Пустой успешный ответ означает отсутствие подходящих операций, а не сбой.
-Согласованное поведение описано в [спецификации журнала](../../../specs/openspec/specs/brokerage-account-ledger/spec.md).
+Согласованное поведение описано в [спецификации журнала](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-ledger/spec.md).
 Фильтр конкретной бумаги и общий режим расширяют исходное описание отдельного
 счёта; их механизм раскрыт на страницах инструментов и общего портфеля.
@@ -109,11 +109,11 @@ Backend публикует статические маршруты под `/api/
 работать с отдельными счетами. При откате сначала возвращается клиент.
 Этот механизм не требует изменения схемы SQLite и миграции финансовых данных.
-Основные спецификации [портфеля](../../../specs/openspec/specs/portfolio-view/spec.md),
+Основные спецификации [портфеля](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md),
-[операций](../../../specs/openspec/specs/brokerage-account-ledger/spec.md),
+[операций](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-ledger/spec.md),
-[дохода](../../../specs/openspec/specs/brokerage-account-income-analytics/spec.md)
+[дохода](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-income-analytics/spec.md)
-и [событий](../../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md)
+и [событий](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-upcoming-events/spec.md)
 описывают отдельный счёт. Общий режим подтверждён действующими маршрутизаторами,
-сервисами и [проверками агрегации](../../../backend/src/modules/investments/all-accounts.spec.ts),
+сервисами и [проверками агрегации](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/all-accounts.spec.ts),
 но не выделен в самостоятельную основную спецификацию. Не следует считать
 описание общего режима изменением требований к отдельному счёту.
@@ -90,8 +90,8 @@ frontend показывает до сотых. Положительное зна
 поэтому ограничение долей действует на все валюты. В общем портфеле проверка
 отрицательных денег выполняется по остаткам счетов до взаимозачёта.
-Нормативные основы: [нормализованный состав](../../../specs/openspec/specs/portfolio-view/spec.md#requirement-нормализованный-состав-portfolio)
+Нормативные основы: [нормализованный состав](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md#requirement-нормализованный-состав-portfolio)
-и [точные значения и валютные агрегаты](../../../specs/openspec/specs/portfolio-view/spec.md#requirement-точные-значения-и-валютные-агрегаты).
+и [точные значения и валютные агрегаты](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md#requirement-точные-значения-и-валютные-агрегаты).
 Структура и общий режим подтверждены реализацией и её проверками;
 отдельных требований к ним в основной спецификации портфеля пока нет.
 Поля транспорта следует сверять с [HTTP API](../../architecture/http-api.md),
@@ -79,9 +79,9 @@ sequenceDiagram
 | Метаданные инструмента | Успешный поиск или подтверждённое отсутствие | Свежими считаются 24 часа; общий кэш на 500 ключей UID/FIGI, ошибки не сохраняются |
 Это параметры текущей реализации, а не самостоятельная политика этого
-документа: [снимки](../../../../backend/src/modules/investments/portfolio/application/portfolio.service.ts),
+документа: [снимки](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/portfolio/application/portfolio.service.ts),
-[метаданные](../../../../backend/src/integrations/tbank/instrument-metadata.service.ts) и
+[метаданные](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/integrations/tbank/instrument-metadata.service.ts) и
-[клиентский запрос](../../../../frontend/src/entities/portfolio/api/usePortfolio.ts).
+[клиентский запрос](https://git.personal.ksv741.ru/WealthLedger/frontend/src/commit/9f7e342333b80bfacfd5bc394a2dcd0613d33ff3/src/entities/portfolio/api/usePortfolio.ts).
 Пять минут — предельный возраст успешного снимка, а не дополнительные
 пять минут после окончания свежих 30 секунд. Запасной ответ сохраняет
@@ -152,7 +152,7 @@ Frontend отображает название и остальные сведе
 источника; его увеличение не является гарантированным исправлением
 ограничения самого T-Bank.
-Проверяемые правила: [свежесть и запасной снимок](../../../../specs/openspec/specs/portfolio-view/spec.md#requirement-свежесть-и-fallback-полного-portfolio-snapshot),
+Проверяемые правила: [свежесть и запасной снимок](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md#requirement-свежесть-и-fallback-полного-portfolio-snapshot),
-[клиентские состояния](../../../../specs/openspec/specs/portfolio-view/spec.md#requirement-состояния-и-ошибки-portfolio-на-клиенте).
+[клиентские состояния](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md#requirement-состояния-и-ошибки-portfolio-на-клиенте).
 Для расследования конкретного значения используйте
 [порядок диагностики](../how-to/investigate-discrepancy.md).
@@ -37,16 +37,16 @@
   теряет цифры, валюту или показатель, исследуйте frontend.
   Если исходные безопасные данные и нормализованный ответ расходятся,
   исследуйте backend. Если не совпадают ожидаемое и описанное поведение,
-   сначала сопоставьте [спецификацию портфеля](../../../../specs/openspec/specs/portfolio-view/spec.md)
+   сначала сопоставьте [спецификацию портфеля](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md)
   и ограничения [потока загрузки](../flows/portfolio-loading.md).
   Исправление документации само по себе не разрешает конфликт требований
   и реализации.
 Для адресной проверки исходников владельцами служат
-[сервис снимков](../../../../backend/src/modules/investments/portfolio/application/portfolio.service.ts),
+[сервис снимков](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/portfolio/application/portfolio.service.ts),
-[валютные итоги](../../../../backend/src/modules/investments/portfolio/infrastructure/tbank-portfolio.mapper.ts),
+[валютные итоги](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/portfolio/infrastructure/tbank-portfolio.mapper.ts),
-[структура](../../../../backend/src/modules/investments/portfolio/domain/portfolio-structure.ts) и
+[структура](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/modules/investments/portfolio/domain/portfolio-structure.ts) и
-[подготовка экрана](../../../../frontend/src/pages/account/ui/AccountPage.vm.ts).
+[подготовка экрана](https://git.personal.ksv741.ru/WealthLedger/frontend/src/commit/9f7e342333b80bfacfd5bc394a2dcd0613d33ff3/src/pages/account/ui/AccountPage.vm.ts).
 Это точки продолжения расследования; смысл вычислений изложен выше.
 Разбор завершён, когда различие объяснено составом, временем или определением
@@ -64,7 +64,7 @@ SQLite не хранит сам портфель: backend получает да
 без логотипа и с подписью результата. Отсутствующие показатели скрываются,
 а не подменяются нулём или заглушкой.
-Существует расхождение: [согласованная спецификация представления позиций](../../../specs/openspec/specs/portfolio-view/spec.md#requirement-представление-карточек-позиций-на-клиенте)
+Существует расхождение: [согласованная спецификация представления позиций](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md#requirement-представление-карточек-позиций-на-клиенте)
 требует доступности всех иных типов в отдельной секции, а текущие frontend
 и его проверка исключают `CURRENCY` только из списка карточек. Такие позиции
 остаются в ответе, валютных итогах, структуре и знаменателе долей остальных
@@ -95,5 +95,5 @@ SQLite не хранит сам портфель: backend получает да
 Для проверки конкретной суммы используйте
 [руководство по расхождениям](how-to/investigate-discrepancy.md).
 Проверяемое поведение отдельного счёта описано в
-[спецификации портфеля](../../../specs/openspec/specs/portfolio-view/spec.md);
+[спецификации портфеля](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md);
 точную форму HTTP-ответа задаёт [OpenAPI backend](../../architecture/http-api.md).
@@ -48,6 +48,6 @@ HTTP-запрос ограничен таймаутом. Сеть, неуспе
 Наличие успешного HTTP-ответа не гарантирует котировку без задержки.
 Условия обработки источника в прогнозе закреплены в
-[спецификации будущих событий](../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-upcoming-events-use-complete-source-results).
+[спецификации будущих событий](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-upcoming-events-use-complete-source-results).
 Точный механизм транспорта, разбора и сопоставления реализован в
-[клиенте MOEX](../../backend/src/integrations/moex/moex.client.ts).
+[клиенте MOEX](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/integrations/moex/moex.client.ts).
@@ -36,7 +36,7 @@ ISIN, даты и ссылки на выпуск. Изменение табли
 После ошибки новая загрузка ограничена минутным интервалом; внутри одного
 HTTP-запроса повторных попыток нет. Обновление запускается следующим обращением
 после истечения кэша, без фонового задания. Точный механизм и сроки принадлежат
-[клиенту НКР](../../backend/src/integrations/ncr/ncr-ratings.client.ts).
+[клиенту НКР](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/integrations/ncr/ncr-ratings.client.ts).
 При отказе реестра показатели облигации отмечают недоступность рейтинга,
 сохраняя остальные доступные показатели. Готовый ответ метрик имеет
@@ -36,7 +36,7 @@ Backend передаёт имя файла `logoName` из метаданных
 Логотипы используются в портфеле, операциях, будущих событиях, поиске и
 страницах инструментов. Отсутствующее имя или ошибка изображения оставляют
 буквенную заглушку и не меняют финансовые значения. Правило построения URL
-принадлежит [форматированию frontend](../../frontend/src/shared/lib/display.ts).
+принадлежит [форматированию frontend](https://git.personal.ksv741.ru/WealthLedger/frontend/src/commit/9f7e342333b80bfacfd5bc394a2dcd0613d33ff3/src/shared/lib/display.ts).
 ## Проверка и сохранение подключения
@@ -96,7 +96,7 @@ sequenceDiagram
 для последующих запросов. Оно не описывает отзыв token на стороне T-Bank.
 Согласованное поведение сохранено в workspace-спецификации
-[T-Bank connection](../../specs/openspec/specs/tbank-connection/spec.md).
+[T-Bank connection](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/tbank-connection/spec.md).
 Точные endpoints и формы ответов определяет backend OpenAPI;
 [HTTP API](../architecture/http-api.md) описывает общую границу.
@@ -126,7 +126,7 @@ Backend хранит token в шифротексте AES-256-GCM с новым n
 | `TBANK_CA_CERT_PATH` | Необязательный путь к доверенному корневому CA в PEM для сетей с TLS-инспекцией; проверка TLS сохраняется |
 Параметры окружения определяет backend
-[validateEnv](../../backend/src/config/env.validation.ts) (workspace-ссылка).
+[validateEnv](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/config/env.validation.ts) (справочный источник).
 Общий FIFO-лимитер ограничивает поток RPC и не допускает более 50
 ожидающих. Для `UNAVAILABLE`, `DEADLINE_EXCEEDED` и `RESOURCE_EXHAUSTED`
 обычный RPC допускает один повтор через секунду. Deadline каждой попытки — 15 секунд,
@@ -139,7 +139,7 @@ Backend хранит token в шифротексте AES-256-GCM с новым n
 отсутствие инструмента, а не временный сбой. Остальные RPC при полной
 очереди завершаются сразу.
 Параметры попыток принадлежат
-[T-Bank client](../../backend/src/integrations/tbank/tbank.client.ts) (workspace-ссылка);
+[T-Bank client](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/integrations/tbank/tbank.client.ts) (справочный источник);
 решение об ограниченных повторах — [ADR 005](../adr/005-tbank-upstream-resilience.md).
 Большое число ранее неизвестных инструментов требует отдельных запросов