Reconcile docs

/polisade:reconcile-docs [SPEC-XXX | DESIGN-XXX | <путь>] — сверка архитектура ↔ код (best-effort)

Показывает расхождения между тем, что утверждает архитектурный корпус docs/architecture/, и тем, что видно в коде. Механическая часть — разрешимость ссылок корпуса (scripts/polisade_reconcile.py anchors, stdlib-only); сама сверка смысла — работа модели клиента на его токенах.

---

⚠️ ЧЕСТНАЯ РАМКА — прочитай и повтори пользователю в КАЖДОМ выводе

┌──────────────────────────────────────────────────────────┐
│  Это МНЕНИЕ модели о расхождениях, а НЕ вердикт.         │
│                                                          │
│  Корпус best-effort (провенанс INFERRED/GAP), код читает │
│  та же модель, и сверяет смысл она же. Ни гейтов, ни     │
│  штампов, ни провенанса CONFIRMED здесь нет — и не       │
│  появится оттого, что список выглядит строго.            │
│                                                          │
│  Детерминированная сверка «дизайн ↔ код» с провенансом   │
│  и блокирующими гейтами — свойство ПЛАТНОГО продукта.    │
└──────────────────────────────────────────────────────────┘

Что это значит на практике:

• пустой список расхождений = «модель ничего не заметила», а не «архитектура соответствует коду»;
• найденное расхождение = «стоит посмотреть», а не «доказано»: корпус мог устареть, код мог быть переименован, модель могла ошибиться в обе стороны;
• механическая часть (anchors) проверяет разрешимость ССЫЛКИ — есть ли файл, существуют ли строки, встречается ли символ. Разрешившаяся ссылка ничего не говорит о верности утверждения;
• сверка с гарантией (оракул-валидированный провенанс, детерминированные гейты целостности корпуса, блокирующая проверка) — отдельный платный продукт; граница описана в docs/what-works-without-paid-parts.md репозитория Polisade Orchestrator (в поставку плагина docs/ не входит).

⛔ Запрещено (класс F1 — «отказ способности подан как положительный факт»): подавать вывод как «дрейфа нет», «архитектура подтверждена», «сверка пройдена», рисовать штампы/галочки соответствия и вешать на вывод exit-код как вердикт. Пиши как есть: «модель заметила N расхождений (best-effort, не проверено)».

⛔ Есть детерминированный сосед, и он не здесь: scripts/polisade_drift_gate.py (api/er, блокирующий в CI). Не выдавай его гарантии за свои и не подменяй его собой — если PM нужен блокирующий чек, отправь его туда.

---

Использование

/polisade:reconcile-docs                 # весь живой корпус docs/architecture/
/polisade:reconcile-docs SPEC-001        # только то, что затронула эта SPEC
/polisade:reconcile-docs src/orders      # только этот участок кода/корпуса

Когда запускать

• Перед передачей проекта другой команде
• Перед следующим крупным SPEC на том же домене
• Перед архитектурным ревью / подготовкой к аудиту
• После завершения всех TASK по SPEC (по решению PM)

---

Алгоритм

Шаг 0 — Контекст и пре-чек

<!-- polisade:silo-legacy POINTER — канон «Силос → корпус» живёт в /polisade:design -->

Силос ≠ корпус. Источник правды по архитектуре — живой корпус docs/architecture/; пакет DESIGN-NNN-<slug>/ — legacy-силос. Прочитал файл из силоса — скажи об этом вслух (переходное чтение). Полный канон — /polisade:design, блок «Силос → корпус»; перевод силоса на корпус — python3 scripts/polisade_migrate_silo.py <пакет> (dry-run по умолчанию).

1. Корень проекта = текущая рабочая директория. Корпус — docs/architecture/.
2. Прочитай .state/knowledge.json (projectContext.techStack, keyFiles) — без него сверка пойдёт вслепую по незнакомому стеку.
3. Аргумент:
   • SPEC-NNN — срез: возьми docs/specs/SPEC-NNN/changeset.yaml (created/modified) и docs/architecture/trace.json; сверяются только перечисленные там объекты корпуса;
   • DESIGN-NNN — legacy-силос: скажи вслух, что читаешь силос (POINTER выше), и сверяй его артефакты; предложи polisade_migrate_silo.py;
   • путь — срез по каталогу;
   • без аргумента — весь корпус.
4. Корпуса нет вовсе (docs/architecture/ отсутствует) — это не ошибка и не расхождение: скажи «сверять нечего, архитектурного корпуса в проекте нет» и предложи /polisade:design (силос) или /polisade:design-corpus (живой корпус, opt-in). Не выдумывай корпус, чтобы было что сверить.

Шаг 1 — Якоря сверки (детерминированно)

python3 {plugin_root}/scripts/polisade_reconcile.py anchors --root . --json

Скрипт перечисляет файлы корпуса, их провенанс и разрешимость каждого code_refs: resolved / missing-file / symbol-not-found / line-out-of-range / outside-root. Это факты о ССЫЛКАХ.

• missing-file / symbol-not-found — кандидат в расхождение (класс missing-in-code), а не готовое расхождение: проверь глазами, не переезд ли это файла;
• no-code-refs — у утверждения нет привязки к коду: механически сверять нечего, только чтением;
• gap (провенанс GAP) — известное-неизвестное корпуса. Не расхождение: корпус честно сказал «не знаю».
• ⛔ Exit-код anchors не вердикт: 0 значит «инвентарь построен».

Шаг 2 — Сверка смысла (субагенты, read-only)

Разложи срез на участки (по bounded-context / каталогу) и запусти fan-out read-only субагентов (Task tool, тип по умолчанию) — по одному на участок, каждый в чистом контексте. Навигация — детерминированный grep-протокол клиента (термины → символы → ссылки), как в /polisade:implement.

⚠️ «Read-only» здесь держится ПРОМПТОМ, а не барьером. Субагент технически может писать: песочницы у бесплатной линии нет, и вредоносный текст внутри корпуса тоже читается как инструкция. Поэтому — снимок до и сверка после (детект, а не защита):

snap() { git rev-parse HEAD; find docs -type f -exec shasum {} \; | sort; }
snap > .polisade/tmp/reconcile-before.txt          # ДО fan-out
# … fan-out субагентов …
snap > .polisade/tmp/reconcile-after.txt           # ПОСЛЕ
diff .polisade/tmp/reconcile-before.txt .polisade/tmp/reconcile-after.txt

Снимок берётся по содержимому (sha каждого файла + HEAD), а не по git status: статус уже-грязного файла ( M, ??) не меняется от новой правки, и такой обход остался бы невидимым.

Расхождение диффа = STOP: кто-то писал в дерево, чего делать не должен. Покажи дифф человеку, ничего не применяй и не «прибирай» за собой — след правки важнее аккуратного вывода.

⚠️ Что этот детект НЕ видит (называем, чтобы его не приняли за барьер): он сравнивает итоговое состояние docs/ и HEAD — значит, пропустит правку с последующим восстановлением тех же байтов, правку вне docs/ (например, в коде или в .state/), и не скажет, КТО правил. Атрибуции у него нет, превенции тоже: барьер, физически закрывающий запись исполнителю, — свойство платного продукта. Здесь его нет, и это сказано вслух.

Промпт субагента — дословно (не пересказывай, не дополняй примерами из чужих проектов):

<!-- polisade:reconcile PROMPT BEGIN -->

═══════════════════════════════════════════
SYSTEM ROLE: Corpus↔Code Divergence Reader (best-effort)
═══════════════════════════════════════════

Ты сверяешь УТВЕРЖДЕНИЯ архитектурного корпуса с тем, что видно в коде
ЭТОГО репозитория, и возвращаешь список расхождений. Ты — READ-ONLY:
не правь ни код, ни корпус, ничего не коммить, ничего не удаляй.

ЧТО ДЕЛАТЬ
1. Прочитай выданные файлы корпуса. Каждое проверяемое утверждение —
   это конкретная фраза/поле/строка, а не «файл целиком».
2. Найди соответствующее место в коде: сначала координаты из code_refs,
   затем grep по терминам утверждения (символ, имя сущности, endpoint).
3. Сравни и запиши расхождение ТОЛЬКО там, где ты видел обе стороны.

ФОРМА ОТВЕТА — JSON, один объект на расхождение:
  id          RC-001, RC-002, … (сквозная нумерация)
  kind        ровно одно из: missing-in-code | missing-in-corpus |
              mismatch | unverifiable
  corpus_ref  путь файла корпуса, где живёт утверждение
  claim       что утверждает корпус (цитата или точный пересказ)
  observation что видно в коде
  code_ref    координата: путь[:символ][:строки] — ОБЯЗАТЕЛЬНА
  confidence  low | medium | high — твоя уверенность
Ничего, кроме этого JSON, в ответе быть не должно.

ЗАПРЕЩЕНО
- Выдавать ВЕРДИКТ. Ты пишешь мнение с уверенностью, а не решение.
  Поля verdict / gate / provenance / certified / passed / stamp и любые
  их синонимы запрещены — приёмник их отвергает (класс F1: отсутствие
  гарантии нельзя подать как гарантию).
- Записывать расхождение, которого ты не видел в коде: если найти место
  не удалось, это kind=unverifiable с честным observation
  «место не найдено: <как искал>», а НЕ «в коде отсутствует».
- Вкладывать в ответ ожидаемые ответы, эталонные решения, координаты
  или имена из ЧУЖИХ наборов задач, бенчмарков и прошлых прогонов:
  работай только с файлами этого репозитория, выданными тебе сейчас.
  Всё, чего ты не прочитал здесь, — не факт, а утечка.
- Править файлы, запускать сборку/тесты, менять git-состояние.

ШУМ НЕ НУЖЕН: расхождения по существу (сущность, поле, контракт,
состояние, зависимость), а не разница в формулировках, порядке или
стиле. Совпало — молчи: «нет расхождения» здесь ничего не гарантирует
и потому не пишется.

<!-- polisade:reconcile PROMPT END -->

Собери ответы субагентов в один список, перенумеруй RC-NNN сквозным порядком и выброси дубликаты (одно и то же расхождение из двух участков).

⛔ Пустой ответ субагента — это «модель ничего не заметила на своём участке», и так его и пересказывай. Не превращай его в «участок соответствует корпусу».

Шаг 3 — Приём расхождений (линт формы + отчёт)

python3 {plugin_root}/scripts/polisade_reconcile.py record --root . --stdin < findings.json

Скелет входа — polisade_reconcile.py template (⛔ не реконструируй форму по памяти). Скрипт проверяет только форму: id, класс из закрытого словаря, координата, названная уверенность, существование corpus_ref. Он пишет .state/reconcile-report.json и ничего больше.

• E-RC-VERDICT-CLAIM — в findings попало поле вердикта. Не обходи его переименованием ключа: это граница продукта, а не придирка линта.
• E-RC-MISSING-FIELD / E-RC-CODE-REF — расхождение без координаты непроверяемо человеком; верни субагента за координатой.
• Ошибки формы → отчёт не записан. Почини вход и повтори.

Перескажи вывод честно: сколько расхождений, каких классов, с какой уверенностью — и рамкой сверху.

Шаг 4 — Что дальше: решает ЧЕЛОВЕК, по одному пункту

⛔ Автоматически не применяется ничего. Ни правка корпуса, ни правка кода, ни коммит, ни «заодно поправил мелочь».

Покажи PM список и по КАЖДОМУ пункту спроси, что делать:

Решение PM	Что делаешь
корпус устарел → поправить корпус	Шаг 5 (отдельный подтверждённый шаг записи)
код разошёлся с дизайном → чинить код	/polisade:defect или /polisade:debt → TASK; код в этом скилле не правится
это нормально	ничего; расхождение остаётся в отчёте как зафиксированное
непонятно	оставь unverifiable, вынеси вопрос в /polisade:questions

Молчание/пустой ответ = не применять ничего. «Он не возразил» — не подтверждение.

Шаг 5 — Правка корпуса (только по подтверждённым пунктам)

⛔ Никогда не пиши в docs/architecture/ ни Write-инструментом, ни cp, ни mv. Единственный писатель живого корпуса — python3 {plugin_root}/scripts/polisade_corpus_io.py (пофайловая атомарность, блокировка прогона и операции, журнал оборванной промоции, backup, отказ на симлинках). Ручная запись обходит всё перечисленное — это регресс.

1. polisade_corpus_io.py status --json — до любого IO. Непустой attention (exit 1) → не начинай: разбери с PM оборванную промоцию.
2. polisade_corpus_io.py acquire --run-id <run-id> --json — блокировка на прогон. E-lock-held → выйди без единой записи, процитировав hint.
3. Собери правки в staging .polisade/tmp/design-corpus/<run-id>/staging/ (тот же формат корпуса — раскладка в skills/design-corpus/references/corpus-layout.md; провенанс правленого файла остаётся INFERRED/GAP — CONFIRMED не ставится никогда).
4. Покажи PM diff staging и дождись подтверждения на этот diff.
5. Промоция одной командой (backup обязателен, если корпус непустой):

python3 {plugin_root}/scripts/polisade_corpus_io.py promote \
    --staging .polisade/tmp/design-corpus/<run-id>/staging \
    --backup  .polisade/tmp/design-corpus/<run-id>/backup \
    --run-id <run-id> --json

6. Любой ненулевой exit — не успех: разбери вывод, при оборванной промоции откатись restore --backup <dir> --run-id <run-id> и halt к PM.
7. polisade_corpus_io.py release --run-id <run-id> — и на успехе, и на halt'е.
8. Правка корпуса — это правка утверждений, а не сокрытие расхождения: DESIGN-DEVIATION-комментарии в коде (audit trail) не удаляются.

---

Формат вывода

════════ СВЕРКА КОРПУС ↔ КОД (best-effort) ════════
Срез: docs/architecture (весь корпус) · файлов: 34 · с привязкой к коду: 21
Ссылки корпуса: 48 · разрешились: 44 · нет файла: 3 · символ не найден: 1
Модель заметила расхождений: 5 (high 1 · medium 3 · low 1)
  RC-001 [mismatch]        docs/architecture/model/entities/Order.yaml
      корпус: поле `discount` типа money
      код:    `discountAmount`, int (копейки) — src/orders/Order.java:31-34
  RC-002 [missing-in-corpus] docs/architecture/model/containers.yaml
      код:    контейнер `notifier` (src/notifier/*) в корпусе не описан
  …
Отчёт: .state/reconcile-report.json
Оговорка: это мнение модели, а не вердикт; пустой список не означает
соответствия; гейтов и штампов здесь нет.
Дальше: решение по каждому пункту — за человеком (правка корпуса / TASK на
код / «так и надо»). Автоматически не применяется ничего.
═══════════════════════════════════════════════════

---

Важно

• Скилл ничего не чинит. Ни код, ни корпус без подтверждения. Правка кода живёт в /polisade:implement через TASK; правка корпуса — Шаг 5, по одному подтверждённому пункту, через примитив записи.
• Отчёт — снимок момента. .state/reconcile-report.json описывает дерево на время прогона; читать его как «текущее состояние» через неделю нельзя.
• Пустой отчёт ≠ соответствие. Он значит «модель не заметила», и разница между этими фразами — ровно то, что продаёт платная линия.
• Корпус best-effort остаётся best-effort. Сверка не повышает его провенанс: INFERRED/GAP до и после; CONFIRMED в бесплатной линии не ставится никогда.
• Связанные команды: /polisade:design-corpus (строит живой корпус, opt-in), /polisade:design (per-SPEC силос), /polisade:defect / /polisade:debt (TASK по расхождению в коде), /polisade:questions (вопросы PM), /polisade:doctor (структурная диагностика артефактов).