reconcile-docs

name	reconcile-docs
description	Show drift between design artifacts and implemented code (advisory)
argument-hint	[SPEC-XXX | DESIGN-XXX]
cli_requires	task_tool

/polisade:reconcile-docs [SPEC-XXX | DESIGN-XXX] — Advisory drift detection

Ручная/advisory команда: показать расхождения между design docs и реальным кодом. Не auto-commit, не удалять audit trail.

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

/polisade:reconcile-docs SPEC-001     # Drift report для DESIGN-PKG привязанного к SPEC
/polisade:reconcile-docs DESIGN-001   # Drift report для конкретного DESIGN package

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

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

Алгоритм

Phase 1 — Контекст

Living-corpus режим (#187, experimental). Если architecture.corpus.mode == "living" в .state/PROJECT_STATE.json, дизайн живёт в едином корпусе docs/architecture/, а не в per-SPEC пакете DESIGN-NNN-*/. Тогда:

• системный слой (C4 L1/L2, glossary, data-model) — system-wide, без single SPEC-parent: реконсиль его против корпуса целиком, а не против одного пакета;
• per-SPEC дельта читается из docs/specs/SPEC-NNN/changeset.yaml + docs/architecture/trace.json (FR → element), не из package-manifest;
• отсутствие per-SPEC DESIGN-PKG — НЕ повод останавливаться (ниже): в corpus-режиме это норма.

1. Прими SPEC-NNN или DESIGN-NNN как аргумент
2. Если аргумент — SPEC:
   • Проверь design_package field в SPEC frontmatter
   • Если design_package: null → сканируй docs/architecture/*/manifest.yaml на parent: {spec_id}
   • Если DESIGN-PKG не найден → сообщи PM и останови:

     У {spec_id} нет DESIGN package. Drift detection невозможен.
     → /polisade:design {spec_id} — создать design package
     

3. Если аргумент — DESIGN-NNN:
   • Найди docs/architecture/DESIGN-NNN-*/manifest.yaml
4. Прочитай manifest.yaml — перечень design-артефактов и realizes_requirements (composite {DOC}.FR-NNN — см. «Requirement ID Scoping» в CLAUDE.md; drift между manifest и sub-artifact frontmatter lint ловит отдельно)
5. Прочитай .state/knowledge.json для контекста проекта (keyFiles, techStack)

Phase 2 — Drift Detection (субагент)

Запусти субагент (Task tool) с ролью:

═══════════════════════════════════════════
SYSTEM ROLE: Design Drift Detector
═══════════════════════════════════════════

Ты — архитектурный ревьюер. Твоя задача — сравнить design docs
с реальным кодом и найти расхождения (drift).

ПРАВИЛА:
- Читай КАЖДЫЙ design-артефакт из manifest
- Для каждого — ищи соответствующий код в проекте
- Отмечай: добавления (+), изменения (~), удаления (-)
- НЕ оценивай качество — только фактический drift

Для каждого артефакта из manifest.yaml.artifacts[]:

Тип	Что сравнивать
openapi (api.md)	Endpoints, methods, request/response schemas, status codes — vs реальные route/controller definitions
erd (data-model.md)	Entities, fields, types, relationships — vs реальные model/migration/schema definitions
c4-container	Containers, technologies — vs реальная структура проекта (packages, services)
c4-context	External systems — vs реальные интеграции в коде
sequence	Flows, call chains — vs реальные вызовы между компонентами
state	States, transitions, guards — vs реальные enum/status definitions и transition logic
glossary	Terms — vs именование в коде (классы, функции, переменные)
asyncapi	Channels, events, payloads — vs реальные producer/consumer definitions

Phase 3 — Drift Report (НЕ auto-commit)

Покажи отчёт:

═══════════════════════════════════════════
DESIGN DRIFT REPORT: {DESIGN-NNN}
Parent SPEC: {SPEC-NNN}
═══════════════════════════════════════════

api.md:
  + POST /sessions: response добавлено поле `refresh_token` (не в design)
  ~ PUT /users/{id}: field `name` → `display_name`

data-model.md:
  + таблица `refresh_tokens` отсутствует в ERD
  ~ User.name → User.display_name

c4-container.md: ✓ соответствует

sequences.md: ✓ соответствует

state-machines.md:
  + состояние `suspended` добавлено в код, нет в диаграмме

Drift items: 5
═══════════════════════════════════════════

Варианты:
  → Обновить design docs (PM подтверждает изменения)
  → Игнорировать (drift зафиксирован, не исправлять)
═══════════════════════════════════════════

Phase 4 — Если PM выбирает обновить

1. Обнови затронутые design-артефакты по данным drift report
2. Обнови manifest.yaml если realizes_requirements изменились
3. Коммит: [{DESIGN-NNN}] Update design docs — reconcile with implementation
4. НЕ удаляй DESIGN-DEVIATION комментарии в коде (audit trail)

Важно

• Это advisory инструмент — не вызывается автоматически
• PM принимает решение обновлять или нет
• При обновлении design docs остаются source of truth
• DESIGN-DEVIATION комментарии в коде — audit trail, не удаляются при reconciliation