docs(finance): C6+C7 finance-tooling epic design spec

Объединённый эпик «Финансы»: наполнение разделов карты C6 (биллинг/тарификация)
+ C7 (бухгалтерия/налоги). 3 новых узла (#61 finance plugin, #62 billing-audit,
#63 ru-tax-accounting) + reuse-классификация + расширенная нормативка
(роутер routing-off-phase.md + наблюдатель 9-атрибутные блоки) + ADR-012.
+9 терминов в cspell-words.txt.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-05-20-finance-tooling-c6-c7-design.md

@@ -0,0 +1,206 @@
+# Дизайн: эпик «Финансы» — наполнение разделов карты C6 + C7 (finance-tooling)
+
+**Дата:** 2026-05-20
+**Статус:** утверждён заказчиком (brainstorming, 20.05.2026)
+**Ветка исполнения:** `worktree-finance-tooling-c6-c7` (worktree от origin/main `7df4786`)
+**Связанные ADR:** ADR-012 (новый — граница finance-tooling)
+**Режим:** экономия 5%
+
+---
+
+## 1. Цель
+
+Закрыть (наполнить) два пустых раздела карты dev-автоматики (`docs/automation-graph.html` / `docs/automation-graph-data.js`):
+
+- **C6** «Финансы — биллинг и тарификация»
+- **C7** «Финансы — бухгалтерия и налоги»
+
+По решению заказчика **разделы объединяются в один комплексный эпик «Финансы»** и решаются вместе. Карта — это «мозг»-маршрутизатор: на задачу «X в финансовом домене» она должна указывать инструмент «Y». Сейчас на оба раздела не указывает ни один узел `NODE_SECTION` (они в списке «пустых разделов — будущих доменов мозга»).
+
+Требование заказчика: **полное покрытие** — каждая реальная потребность домена сопоставлена с узлом (а не 1–2 точечных инструмента).
+
+## 2. Контекст
+
+### 2.1. Что уже есть в коде (объект домена)
+
+Биллинг-подсистема Лидерры (Plan 4) — подтверждённые файлы:
+
+- `app/app/Services/Billing/PricingTierResolver.php` — 7-ступенчатая тарификация (pure).
+- `app/app/Services/Billing/LedgerService.php` — двойной баланс prepaid→₽ через `bcmath`.
+- `app/app/Services/Billing/BillingTopupService.php`, `ChargeResult.php`.
+- `app/app/Models/PricingTier.php`, `LeadCharge.php`; `app/app/Repositories/PricingTierRepository.php`.
+- `app/app/Http/Controllers/Api/{AdminPricingTiersController,AdminBillingController,BillingController,TenantChargesController}.php`.
+- `app/app/Jobs/Supplier/CsvReconcileJob.php` — hourly сверка, алерт при дрейфе >5%.
+- `app/app/Services/Reports/Providers/BillingSummaryProvider.php` — отчётность.
+- `app/app/Mail/TopupSuccessNotification.php`, `ZeroBalancePausedMail` (auto-pause при нуле).
+
+C6 = «как Лидерра берёт деньги с клиентов за лиды» (тарифы, списания, баланс, сверка, авто-пауза). C7 = «учёт и налоги компании» (бухгалтерия, НДС/УСН, отчётность). Бухгалтерия компании в основном вне dev-репо (1С/аутсорс) — поэтому C7 dev-tooling скуднее C6.
+
+### 2.2. Нормативная поверхность маршрутизации (актуальная на 20.05.2026)
+
+С iter9 (ADR-011, brain governance) маршрутизация описана явно:
+
+- `docs/router-procedure.md` v1.0 — 5-шаговая процедура «task → node(s)»; **читает** 9-атрибутный реестр Tooling §4.X (generic, перечень узлов не хардкодит).
+- `docs/routing-off-phase.md` v1.1 — таблица «триггер → off-phase узел» (§4.11–§4.35) + 12 канонических связок L1–L12.
+- Наблюдатель (observer): 9-атрибутные блоки на каждый узел реестра (Tooling §0.1 шаблон) + контролёры lefthook (C1 l1-watcher name@source, C2 cross-ref-checker).
+
+**Следствие:** новые узлы обязаны попасть в routing-таблицу (роутер) и получить 9-атрибутные блоки + пройти контролёров (наблюдатель). Это расширяет нормативную правку сверх классических 4 файлов.
+
+## 3. Решение по объёму
+
+**Гибрид с полным покрытием:** reuse-классификация существующих узлов в C6/C7 + установка релевантного marketplace-плагина + два своих проектных скила под реальные gap'ы + честная регистрация неприменимого как not-applicable/DEFERRED.
+
+## 4. Архитектура решения — слои
+
+| Слой | Содержание |
+|---|---|
+| **Установка (1 узел)** | `finance` plugin (knowledge-work-plugins, Anthropic) — enable в `~/.claude/settings.json` (marketplace уже добавлен; механика как operations/product-management). |
+| **Свои скилы (2 узла)** | `.claude/skills/billing-audit/` (C6) + `.claude/skills/ru-tax-accounting/` (C7). |
+| **Reuse-классификация** | ~11 существующих узлов → C6/C7 через `NODE_SECTION_SECONDARY` (основная привязка `NODE_SECTION` 1:1 не трогается). |
+| **DEFERRED / not-applicable** | warehouse-MCP плагина (Snowflake/Databricks/BigQuery) — не наш стек; SOX-скилы — нет SOX у частной РФ-компании. |
+| **Нормативка** | Tooling Прил.Н, PSR_v1, Pravila, CLAUDE.md, routing-off-phase.md, router-procedure.md, ADR-012. |
+| **Карта** | +3 узла + рёбра + secondary-классификация + META/версии. |
+
+## 5. Новые узлы
+
+### 5.1. #61 — `finance` plugin (knowledge-work-plugins)
+
+- **Тип:** plugin (enable), Anthropic Verified, тот же marketplace, что operations #51 / product-management #42.
+- **Состав:** 9 скилов — `reconciliation`, `variance-analysis`, `financial-statements`, `close-management`, `journal-entry`, `journal-entry-prep`, `sox-testing`, `audit-support`, плюс MCP-серверы (snowflake/databricks/bigquery/slack/ms365 — http).
+- **Домашний раздел:** **C7** (primary) — плагин на ~80% бухгалтерский.
+- **Применимость к РФ-контексту (честно):**
+  - ✅ применимо: `reconciliation` (сверка ledger↔банк/субледжер — cross-ref в C6 под `CsvReconcileJob`), `variance-analysis` (план/факт выручки — C6/C7).
+  - ⚠️ частично (US-GAAP, у нас РСБУ): `financial-statements`, `close-management`, `journal-entry`, `journal-entry-prep` — концепция применима для внутренней управленческой отчётности; форма/план счетов отличаются.
+  - ❌ not-applicable РФ: `sox-testing`, `audit-support` (SOX 404 — США; у частной РФ-компании SOX отсутствует).
+- **MCP-серверы:** **DEFERRED / не используем** — Snowflake/Databricks/BigQuery не в стеке (PG 16 + Redis); ms365/slack — не подключены. Фиксируем как not-applicable (аналог Figma MCP #44 deferred-pending).
+- **Smoke:** после enable — скилы `finance:*` доступны в списке скилов сессии.
+
+### 5.2. #62 — `billing-audit` (свой проектный скил, C6)
+
+- **Тип:** self-authored project skill (`.claude/skills/billing-audit/`), как `process-analysis`, `audit-portal`, `regression` — не вендоренный, линтуется.
+- **Зачем:** generic-инструменты не кодируют **денежные инварианты именно Лидерры**.
+- **Scope (чек-лист + процедура аудита при правке/ревью биллинг-кода):**
+  1. сохранение суммы prepaid→₽ через `bcmath` без утечек/потери копеек;
+  2. идемпотентность списания (один лид = одно списание; повтор/ретрай не дублирует);
+  3. корректность резолюции 7 ступеней `PricingTierResolver`;
+  4. интерпретация дрейфа `CsvReconcileJob` (порог >5%) — что значит, куда смотреть;
+  5. провенанс `charge_source` (откуда возникло списание).
+- **Границы (FIN5):** ≠ `process-modeling`/`process-analysis` (#52/#53 — *поток/процесс*, billing-audit — *денежная корректность реализации*); ≠ D3 audit-security/audit-portal (#39/#40 — *безопасность/портал целиком*, billing-audit — *деньги*). Объект анализа иной.
+- **Состав:** `SKILL.md` + `references/` (инварианты, ссылки на файлы биллинга) + `evals/evals.json` (триггер-eval).
+
+### 5.3. #63 — `ru-tax-accounting` (свой проектный скил, C7)
+
+- **Тип:** self-authored project skill (`.claude/skills/ru-tax-accounting/`).
+- **Зачем:** `finance`-плагин — US-GAAP/SOX; РФ-специфика (РСБУ + НК РФ) им не покрывается. Закрывает налогово-учётный gap C7 явно (по решению заказчика — вместо DEFERRED).
+- **Scope:** контекст РСБУ vs управленческий учёт; налоговые режимы (НДС / УСН доходы/доходы-расходы) применительно к SaaS-выручке за лиды; маппинг billing-выручки (`lead_charges`, `LedgerService`) → налоговая база; подготовка выгрузок/документов для бухгалтера; что является налогооблагаемым событием (списание / пополнение / возврат).
+- **Границы (FIN6):** ≠ `finance` plugin #61 (тот — generic/US-механика учёта + reconciliation/variance; ru-tax — РФ РСБУ/НК специфика); ≠ D1 «Юриспруденция/договорная» (договоры/право, не налоги); ≠ D2 «Защита ПДн» (персональные данные, не налоги).
+- **Состав:** `SKILL.md` + `references/` (РСБУ/НК РФ заметки, налоговые режимы) + `evals/evals.json`.
+
+## 6. Reuse-классификация (существующие узлы → C6/C7)
+
+Через `NODE_SECTION_SECONDARY` (узел остаётся в своём primary `NODE_SECTION`, добавляется вторичная привязка).
+
+**→ C6 (биллинг/тарификация):**
+
+| Потребность | Узел |
+|---|---|
+| Биллинг-модели (LedgerService/PricingTierResolver/lead_charges/tenants) | Boost #10 |
+| Тесты денежной логики (ступени, ledger, идемпотентность, гонка lockForUpdate) | Pest #18 + pest-parallel-debugger |
+| Money-precision статанализ (bcmath, без float) | Larastan #12 |
+| Runtime-ошибки списаний / auto-pause | Sentry MCP #34 |
+| Очередь `CsvReconcileJob` / кэш баланса | Redis MCP #35 |
+| Метрики выручки/тарифов (MRR, tier-распределение) | product-management metrics-review #42 |
+| Прогноз/моделирование выручки | data-scientist #49 |
+| Себестоимость поставщика (`supplier_lead_costs`) | operations vendor-review #51 |
+| Финансовый риск / дрейф сверки | operations risk-assessment #51 |
+| State-машина charge-lifecycle / discovery | process-modeling #52 / process-analysis #53 |
+| Доки bcmath / money-lib | context7 #60 |
+| Сверка ledger↔субледжер | finance `reconciliation` #61 (cross-ref) |
+| Анализ отклонений выручки | finance `variance-analysis` #61 (cross-ref) |
+
+**→ C7 (бухгалтерия/налоги):**
+
+| Потребность | Узел |
+|---|---|
+| Управленческая отчётность / финмодели | data-scientist #49 |
+| Выгрузка billing→учёт (данные) | Boost #10 / Pest #18 |
+| Финансовый риск / комплаенс-трекинг | operations risk-assessment / compliance-tracking #51 |
+| Сверка / отклонения / отчётность (US-механика) | finance plugin #61 (primary) |
+| РФ РСБУ / НК РФ / НДС-УСН | ru-tax-accounting #63 |
+
+> `BillingSummaryProvider.php` — это код-объект (отчётный провайдер), не узел тулчейна; упоминается как объект, на который указывают узлы, не получает номер.
+
+## 7. Граница C6 ↔ C7 (FIN7)
+
+- **C6 биллинг/тарификация** = начисление денег клиенту за лиды: тарифные ступени, списания, баланс, top-up, сверка поставки, авто-пауза.
+- **C7 бухгалтерия/налоги** = учёт и налоги компании: РСБУ, НДС/УСН, отчётность, налоговая база, закрытие периода.
+- Точка стыка: billing-выручка (`lead_charges`/`LedgerService`) — это **выход C6** и **вход C7** (источник налоговой базы). Скилы не пересекаются: billing-audit проверяет корректность *начисления*; ru-tax-accounting переводит выручку в *налоговый/учётный* контекст.
+
+Фиксируется в **ADR-012**.
+
+## 8. Нормативная поверхность (8 артефактов)
+
+1. **Tooling Прил.Н** — §4.36 finance plugin / §4.37 billing-audit / §4.38 ru-tax-accounting (каждый: 9-атрибутный блок наблюдателя + проза); §0 счётчик **+3** (база сверяется из Tooling §0 «КАНОН СЧЁТЧИКОВ» на этапе нормативки — ожидаемо 60→**63**) + новая off-phase подкатегория `finance-tooling`; header bump.
+2. **PSR_v1** — R10.1 +3 строки (finance plugin в блок плагинов; 2 скила — блок скилов/note). Не UI → вне R6.0/R6.1/R14. Version bump.
+3. **Pravila** — §13.2 +абзац «Off-phase finance-tooling». Version bump.
+4. **CLAUDE.md** — §3.3 +#61/#62/#63 (однострочный индекс, пин на Tooling §4.36–§4.38); §0 cross-refs bump; §6 +абзац; §9 +entry; шапка bump. Прямой Edit (worktree-эксцепшн §5 п.10).
+5. **routing-off-phase.md** (роутер) — +3 строки routing-таблицы (триггеры → #61/#62/#63); +каноническая связка **L13** (finance-цепочка); scope-диапазон §4.11→§4.38; version v1.1→v1.2.
+6. **router-procedure.md** (роутер) — changelog-touch (узлы появляются в реестре §4.X, который процедура читает; перечень generic — структурных правок не требует).
+7. **ADR-012** — `docs/adr/012-finance-tooling.md`: граница C6↔C7; applicability finance plugin (US-GAAP/SOX vs РФ); billing-audit vs process-*/D3; ru-tax vs finance/D1/D2; DEFERRED warehouse-MCP.
+8. **Наблюдатель** — 9-атрибутные блоки (п.1) + прогон контролёров **C1 l1-watcher** (name@source consistency) + **C2 cross-ref-checker** → GREEN/WARN-only на новых узлах (контролёры warn-only `|| true`, но дрейф по новым узлам не вносим).
+
+## 9. Карта (`automation-graph-data.js` + `automation-graph.html`)
+
+- **+3 узла** в `NODES`: `finance_plugin` (group plugins/skills_proj), `billing_audit` (skill), `ru_tax` (skill).
+- **NODE_SECTION:** `finance_plugin: 'C7'`, `billing_audit: 'C6'`, `ru_tax: 'C7'`.
+- **NODE_SECTION_SECONDARY:** `finance_plugin: ['C6']` + reuse-привязки из §6 (Boost/Pest/Larastan/Sentry/Redis/PM/data-scientist/operations/process-*/context7 → добавить 'C6' и/или 'C7').
+- **EDGES:** связи новых узлов с соседями (billing_audit → Pest/Boost; finance_plugin → operations/PM; ru_tax → finance_plugin).
+- **NODE_DETAILS** в `automation-graph.html`: описания/`together`/`boundaries` для 3 узлов.
+- **META/версии-метки:** обновить счётчики узлов/рёбер и версию-метку узла `claude_md` (актуальная версия определяется на этапе нормативки) после нормативки.
+
+## 10. Конфликт-аудит (для плана)
+
+| Код | Риск | Резолюция |
+|---|---|---|
+| FIN1 | warehouse-MCP finance не под стек | DEFERRED / not-applicable, не подключаем |
+| FIN2 | SOX-скилы (sox-testing/audit-support) | not-applicable РФ (нет SOX) |
+| FIN3 | finance vs operations (vendor-review/risk) | finance = учёт/сверка/отчётность; operations = операционные процессы/риск |
+| FIN4 | finance `reconciliation` vs `CsvReconcileJob` | инструмент (скил) vs код (наш джоб) — не конфликт, скил помогает анализировать джоб |
+| FIN5 | billing-audit vs process-*/audit-portal/D3 | объект иной (деньги vs поток vs безопасность) |
+| FIN6 | ru-tax vs finance plugin vs D1/D2 | ru-tax = РФ РСБУ/НК; finance = US-механика; D1 = право; D2 = ПДн |
+| FIN7 | граница C6↔C7 | ADR-012: начисление клиенту vs учёт/налоги компании |
+| FIN8 | lint вендоренного/enabled | self-authored скилы линтуются; finance-плагин — в plugin-cache, не в репо |
+
+## 11. Изоляция и исполнение
+
+- **Worktree** от origin/main `7df4786` (= текущий main, superset iter9), ветка `worktree-finance-tooling-c6-c7`. Свежий worktree без gitignored-файлов — node_modules/vendor через junction, bin/.env скопированы.
+- **Коммиты явными путями** (`git commit -- <пути>`) — параллельные сессии активны (memory `feedback_git_commit_explicit_paths`).
+- **Субагенты + git** — только Sonnet/Opus (Pravila §15.1), верификация commit-базы после каждого.
+- **Pre-flight sync** (Pravila §15.2) перед правкой каждого из 8 нормативных файлов: `git fetch && git log HEAD..origin/main --oneline`.
+
+**Фазы (один план):**
+
+1. **Фаза 1 — C6:** скил `billing-audit` (TDD: triggers-eval first) + reuse-классификация C6 в карте.
+2. **Фаза 2 — C7:** enable finance plugin (+smoke) + скил `ru-tax-accounting` (TDD) + reuse-классификация C7.
+3. **Фаза 3 — нормативка + роутер + наблюдатель + карта + ADR:** Tooling/PSR_v1/Pravila/CLAUDE.md + routing-off-phase.md/router-procedure.md + ADR-012 + automation-graph + 9-атрибутные блоки + прогон C1/C2.
+
+## 12. Тестирование / верификация
+
+- Скилы: триггер-eval (как discovery-interview 20/20) — `evals.json` на оба скила; near-miss к соседним узлам (process-analysis/D3/finance plugin/D1) уходят корректно.
+- Нормативка: markdownlint + cspell (lefthook) GREEN; lychee на изменённых .md (pre-push).
+- Карта: JS-smoke (узлы парсятся, NODE_SECTION покрывает все узлы, рёбра валидны) — как iter8/iter9.
+- Контролёры: C1 l1-watcher + C2 cross-ref-checker без новых drift по добавленным узлам.
+- Перед коммитом — pre-commit (docs-only коммиты: markdownlint/cspell/gitleaks; PHP-коммиты скила-evals при наличии PHP — pint/larastan/pest).
+- Регрессия `/regression quick` перед закрытием; full — по необходимости.
+
+## 13. Out of scope (YAGNI)
+
+- Реальная интеграция платёжного провайдера (карты) — Б-1 blocked, отдельный ADR.
+- Подключение warehouse-MCP (Snowflake/Databricks/BigQuery) — не наш стек.
+- SOX-процедуры — неприменимо РФ.
+- Автоматизация бухгалтерии в 1С — вне dev-репо.
+- UI/функциональные правки биллинг-подсистемы — это эпик тулчейна/карты, не продукта.
+
+## 14. Критерий готовности
+
+- Разделы C6 и C7 карты непустые (есть узлы); 3 новых узла формализованы во всех 8 нормативных артефактах согласованно; роутер знает новые узлы; наблюдатель имеет 9-атрибутные блоки; ADR-012 фиксирует границы; регрессия GREEN; запушено `origin <ветка>:main`.