docs(#116): решения плана 1 (P1-1…P1-31, R-1…R-8 плана 1) в design.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

openspec/changes/unified-statement-normalization/design.md

@@ -1324,3 +1324,42 @@ line_name, line_name_confidence, parent_ref, values}`: `line_code` — разо
 101. **P0-4. `ARM_KA_DOCS` в scan-gateway**: тест идентичности scan-gateway читает `ARM_KA_DOCS` (спека называет переменную); поиск `fixtures` не меняется. Цена: расхождение в `dev/checks.md` сужается до fixtures.
 102. **P0-5. OpenSpec change `contract-identity-window` в tabular-parser и scan-gateway**: MODIFIED требования «Копия контракта идентична источнику» (прежний текст «байт в байт равны `../docs/contracts/`» на окне неверен); arm-core change не получает — правило описано в спеке docs `recognition-contract`. Цена: у arm-core при закрытии нет `openspec archive`.
 103. **R-1 (план 0). Дорожку плана 0 исполняет фоновый агент на sonnet**: а не сама сессия: сессия координирует четыре параллельные дорожки (планы 0, 1, 3А, 6). Метод — executing-plans (Native, ≤5 задач), ревью всей ветки — opus. Цена: слабее контекст сессии при финальных рулингах; страхует ревью и таблица находок.
+104. **P1-1.** Конфиг линтеров пакета — только в корневом `pyproject.toml` репозитория `arm-statements` (в дерево `arm_statements/` не входит и в хост не копируется): `ruff.toml` внутри `arm_statements/` по иерархии ruff перекрыл бы конфиг хоста, а спека требует «конфиг хоста применяется к копии». Код пакета написан под самый строгий конфиг, так что он проходит любой хост. Цена: «конфиг линтеров вместе с копией» (формулировка спеки) читается как «код, проходящий конфиг», а не как файл; см. O-1.
+105. **P1-2.** Версии инструментов пакета — пины scan-gateway (`ruff==0.16.10`, `mypy==2.4.0`, `pytest==9.1.1`): это единственный хост с явными пинами; у tabular-parser и arm-core `>=`, в их окружениях встречаются ruff 0.16.10–0.17.1. Цена: новая версия ruff в хосте может найти новое замечание в копии; см. O-2.
+106. **P1-3.** `PLR2004` в тестах пакета не отключается: `per-file-ignores` хостов (`tests/**` у scan-gateway) на копию `api/arm_statements/tests/` не распространяются. Цена: числа в тестах — кортежами и `D("…")`.
+107. **P1-4.** Ничья редакций при `effective = None` — `edition = None`, неуверенный код подтверждён только при подтверждении в обеих редакциях. Цена: лишняя подсветка кода у формы без даты (она и так `needs_check` — `PERIOD_UNKNOWN`).
+108. **P1-5.** «Книга xlsb без числовых форматов» шаг 4 узнаёт по предупреждению адаптера `XLSB_NO_FORMATS` в `FormCandidate.warnings` — отдельного поля у кандидата спека не задаёт. Цена: адаптер Excel обязан класть это предупреждение в кандидат каждой формы книги xlsb.
+109. **P1-6.** У `DISCLOSURE` предупреждения шапки не выдаются, статус всегда `done` (спека: «`DISCLOSURE` — `done` без условий»). Цена: пустая шапка пояснений не видна предупреждением.
+110. **P1-7.** Код Excel из текстовой ячейки с заменой двойника — неуверенный (≤ 99) и проходит структурную проверку, как OCR; «у Excel `needs_review` по структуре не ставится» прочитано как «у чистых кодов Excel» (уверенность 100). Цена: редкий текстовый код «I1О0» в Excel может подсветиться.
+111. **P1-8.** Строка правки (`row_index = None`) у ядра участвует в §7 и в выборе варианта, только если у неё есть сумма; в структурной последовательности и как родитель `detail` — нет (позиции в файле нет). Цена: код правки не служит якорем для подтверждения соседних неуверенных кодов.
+112. **P1-9.** Двухстрочный заголовок склеивается, когда подпись верхней строки отдельно — не период, а «верхняя + нижняя» — период («На 30 сентября» + «2025 г.»; нижняя «2025 г.» сама по себе дала бы ошибочное 31.12.2025). Цена: заголовок в два ряда без даты не склеивается (колонка всё равно остаётся по числам); если над строкой заголовка стоит посторонний текст, который вместе с нижней подписью случайно читается как период, подпись склеится.
+113. **P1-10.** Текстовая сумма без пробелов длиннее 16 целых цифр — `amount = null`, `string_value` = текст, `is_recognized = false`, без `VALUE_OUT_OF_RANGE` (предупреждение — только для числового `value` Excel, как в спеке).
+114. **P1-11.** `COLUMN_DATE_UNCERTAIN` проверяется только у абсолютных подписей: относительные даты вычисляются от эффективной даты и в ожидаемые входят по построению.
+115. **P1-12.** Поля шапки, правила которых спека не задаёт: `okpo`, `okopf`, `okfs` — только цифры; `okud` — первое совпадение `0710\d{3}`; `organization_name`, `address` — текст без пробелов по краям.
+116. **P1-13.** В словарь пакета `statement_headers.yaml` переезжают и метки шапки Excel (`labels`, `auditor`, `legal_form`) — proposal: «`statement_headers.yaml` переезжает в пакет»; у tabular-parser не остаётся своего словаря форм. Цена: в общем словаре есть данные, которыми пользуется один адаптер.
+117. **P1-14.** «Под подписью» в правиле (а) столбца кодов — ячейки столбца ниже подписи до конца сегмента.
+118. **P1-15.** `FailedRelation` несёт и `column_index`, и `column_key` — чтобы ядро получало нарушения в своих ключах колонок без обратного сопоставления.
+119. **P1-16.** Перечень кодов копируется из ветки docs `feat/116-unified-normalization` до слияния docs PR #117.
+120. **P1-17.** Столбец правее кода без подписи, но с числами, в сегменте с заголовком — колонка с `label = ""`, `period_kind = none` и `COLUMN_WITHOUT_DATE` (`error`): «числовая колонка без разобранной подписи» по таблице уровней.
+121. **P1-18.** Заголовок есть у одного из сегментов, но не у первого — колонки документа задаёт первый сегмент с заголовком (спека: «остальные сегменты берут его колонки»), `column_index` — номера столбцов этого сегмента.
+122. **P1-19.** Документ `BALANCE` / `INCOME` без строк (`CODE_COLUMN_NOT_FOUND`) получает `form_variant = full`: в схеме v2.0 `form_variant` обязателен и `null` только у `DISCLOSURE`.
+123. **P1-20.** При `accepted` (у ядра) правило «`needs_review` у всех ячеек несошедшегося жёсткого соотношения» не применяется: иначе акцепт снимал бы нарушение со статуса, а подсвеченные им ячейки держали бы `needs_check` через условие «нет значений с `needs_review`» (спека: «`accepted` ⇒ жёсткие нарушения статус не держат»). У сервиса `accepted` всегда ложно. Цена: после акцепта ячейки несошедшегося соотношения не подсвечиваются (нарушение видно в `checks`).
+124. **P1-21.** `FailedRelation.expected` / `actual` (и `RelationOutcome`) — `Decimal | None`: `None` — цель или все члены пусты; такое посчитанное соотношение — всегда нарушение (допуск не применяется). Контракт v2.0 так и задаёт (`expected` — `money`, «`null` — цели нет»; `actual` — `money`), агрегат ядра тоже не превращает пустое в 0 (план 3, Review Focus 2). Цена: хосты и ядро обрабатывают `None` в тексте нарушения («пусто»); при ошибке — `0` вместо пустоты прятал бы «пустую цель» в допуск ±1 (`1600 = 0` при пустом `1700` считалось бы сошедшимся).
+125. **P1-22.** Две публичные нормализации текста: `normalize_label` (дословно `normalize_text` tabular-parser — пунктуация сохраняется; под неё записаны перенесённые из tabular-parser метки шапки, заголовки, ОКУД, маркер продолжения) и `normalize_caption` (подписи колонок, единицы, относительные периоды). Таблица «ключ словаря → нормализация» — в разделе API; `type_hint` и `is_continuation` пакета пользуются `normalize_label`. Цена: новый синоним пишется под нормализацию своего ключа; ошибка — синоним молча не срабатывает (ловят тесты пакета на синтетике и покрытие словарей в tabular-parser, O-8 плана 4).
+126. **P1-23.** Новый код `XLS_NO_CODEPAGE` (`info`, файл): книга xls без кодовой страницы — заметка читателя, относящаяся ко всей книге (и к формам, и к ОСВ). Строки добавлены в таблицу спеки «Шаг 8 — предупреждения» и §11.9 `05-domain-rules.md` (правило спеки: «новый код вводится словарём пакета и таблицей §11»). Цена: tabular-parser выдаёт его в `metrics.warnings` вместо `OSV_XLS_NO_CODEPAGE` в каждом документе ОСВ (план 4, P4-13); экран показывает его в карточке файла, а не у листа ОСВ.
+127. **P1-24.** `resolve_relative(ABSOLUTE | NONE, …)` → `None`, а не исключение: у таких колонок дата не вычисляется, а ядро перебирает колонки формы одним циклом. Цена: вызов с неверным видом не заметен (ядро зовёт функцию только для `relative:*`, план 3 B2).
+128. **P1-25.** `choose_edition(document_type, codes: Sequence[tuple[str, bool]], effective, rules, *, variant=None)` вместо запрошенной `choose_edition(effective, codes, rules)`: перечень кодов зависит от формы и варианта, а «лучшая подпоследовательность» по спеке сравнивает сначала число **уверенных** кодов — без типа и признака уверенности результат расходился бы с `recompute`. `confirm_codes` и `recompute` берут редакцию этой же функцией. Цена: ядро передаёт пары `(код, уверенный)`, собранные из строк результата (`line_code_confidence == 100`).
+129. **P1-26.** Перевод выхода в форму контракта v2.0 (`to_contract`, `warning_to_contract`) — в пакете, а не в каждом сервисе: одно уплощение шапки, одно правило «необязательные ключи без `null`», один отброс `column_key`. Пакет теперь знает форму `statementDocument` v2.0. Цена: новый MAJOR контракта меняет и пакет (синхронизация копий — план 2), а модель контракта хоста валидирует `dict` пакета — расхождение видно тестом схемы хоста, а не пакета.
+130. **P1-27.** Статус документа — функция документа: `status_input(StatementDocument)` (конвейер считает им `status`) и `status_input_from_contract(dict)` для ядра (страховка `document.status` результата 2.0); свойство `status_input_from_contract(to_contract(d)) == status_input(d)` закреплено тестами задач 19 и 20. `layout_found` выводится из «строки есть» (строк нет ⇔ столбец кодов не найден, задача 17 п. 2). Цена: если в будущем появится документ со столбцом кодов, но без строк, функции нужен явный признак раскладки.
+131. **P1-28.** `code_column(rows, rules, *, relaxed)` и `amount_columns(rows, code_col, rules, *, source)` — публичные обёртки шага 2 над сеткой `Cell` (адаптер Excel строит её из листа); минимум ослабленного поиска и слабого продолжения — данные словаря (`min_codes_continuation: 1`, был литерал «минимум один» в коде шага 2 и `min_codes_continuation` tabular-parser). `relaxed` задаётся типом формы, а не внутренним `CodeSection`. Цена: адаптеру нужна сетка `Cell` листа, чтобы спросить столбец кодов (у tabular-parser она уже есть — `grid_rows` плана 4).
+132. **P1-29.** `form_name` — поле `StatementHeader` (в контракте он в `header`), а не `StatementDocument`; ставит конвейер из `evidence.title.text` как есть, `parse_header` оставляет `None`. Цена: хост, собирающий шапку `parse_header` сам (без конвейера), заголовка не получит — таких вызовов в планах нет.
+133. **P1-30.** Коды предупреждений — `WarningCode` (`StrEnum`) в `issues.py`; загрузчик требует равенства множества кодов словаря и перечисления; `make_warning` с неизвестным кодом — `KeyError`. Цена: новый код — две правки в пакете (словарь + член перечисления) и строка §11.9 docs; опечатку в коде хоста ловит mypy (член перечисления), а строковый литерал — только `KeyError` при вызове.
+134. **P1-31.** `Rules.code_orders.sequence(…, DISCLOSURE, …)` → `()`, а не `KeyError`: у пояснений перечня нет, и структурная проверка, и проверки ядра по редакции к ним не применяются. Цена: вызов для пояснений молча даёт пустой перечень.
+135. **R-1 (план 1). Дорожка плана 1 — фоновый SDD-контроллер на sonnet**: дорожки волны 1 (планы 0, 1, 3А, 6) идут параллельно четырьмя фоновыми агентами; исполнители задач — sonnet, финальное ревью ветки — opus. Цена: слабее контекст сессии; страхуют пошаговые ревью и таблица находок.
+136. **R-2 (план 1). Р-34 и Р-43 учтены в брифах**: подтверждение кода — флаг `code_fixed` (`is_confirmed`), уверенность не меняется; `arm-statements` внесён в таблицу workspace (`CLAUDE.md` workspace, `context/00-workspace-layout.md`, коммит e6eef27 ветки feat/116). Цена: нет.
+137. **R-3 (план 1). `parse_code`: краевая `|` — как в спеке**: `|` → 1, если результат в кодовом диапазоне (строка 178 spec.md), допустимы 4–5 цифр: «1220|» → 12201, «|1220» → 11220 с `fixed=True` (подсвечивается). Не менялось: буквальное чтение спеки. Цена: код с краевой чертой OCR становится пятизначным с подсветкой; вопрос владельцу спеки (кандидат в follow-up). Ledger I-2 (T4).
+138. **R-4 (план 1). Тест плана `test_sublines` исправлен по спеке**: тест плана (1230 = 10 против 4 + 5 = 9) противоречил допуску ±1 мягких соотношений (расхождение 1 — в допуске); оставлено поведение по спеке, тест заменён парой (4+4 → нарушение, 4+5 → нет). Цена: если для подстрок хотели строже — допуск подстрок 0 вместо ±1.
+139. **R-5 (план 1). Неуверенный код вне перечня редакции не подтверждается структурой**: спека явного правила не даёт; по общему «подтверждён ⇔ входит во все лучшие подпоследовательности», а код вне перечня в последовательность не входит. Цена: неуверенный нестандартный код из OCR получает `needs_review` (безопасная сторона).
+140. **R-6 (план 1). История ветки feat/1-arm-statements-package переписана `git filter-branch --msg-filter`**: один коммит имел трейлер «Claude Sonnet 5.5» вместо требуемого «Claude Opus 5.5»; ветка не публиковалась. Цена: SHA коммитов в ledger/отчётах до переписи устарели.
+141. **R-7 (план 1). Решения исполнителей задач при пробелах спеки**: T6.2 (смешанные/повторные разделители суммы → цифры подряд ≤ 16 и `is_recognized=false`; excel допускает ≥ 3 знака после разделителя); T10.1–T10.4 (`SEGMENT_WITHOUT_CODES` только если столбец кодов найден хотя бы у одного сегмента; ослабленный поиск включается, когда строгий не нашёл и отрезок известен; сегмент двухстрочной повторной шапки открывается строкой с подписью кода; сопоставление по датам требует разных целевых колонок); T11.2 (сегмент без столбца кодов — наименование слева, значения по `value_cols` или правее наименования); T14.3–T14.4 (ничья без даты — `edition=None`, подтверждено в обеих; родитель пятизначного — ближайшая выше строка с нужным кодом, уверенная или подтверждённая); T15.2 («строгое большинство» знака = более 50 %). Ревью задач: со спекой не расходятся. Цена: перечисленные трактовки при пробелах спеки; пересмотр — правкой кода пакета и словарей.
+142. **R-8 (план 1). Расширение публичного API сверх раздела плана**: в `__all__` добавлены `Rules` (нужен хостам в сигнатурах) и `RulesError` (обработка `load_rules`); абзац про них — в README пакета. Цена: хосты могут зависеть от двух лишних имён.