type: standard
aspect: process
title: "Реабилитация документации"
version: 1.0.0
date: 2026-03-30
status: active

Реабилитация документации

Назначение: Структурированный курс восстановления документации после томографии
Пара: Томография (диагностика) → Реабилитация (восстановление)

ОПРЕДЕЛЕНИЕ

Реабилитация — последовательный курс сеансов, каждый из которых атомарно
приводит часть документации в соответствие с целевой структурой.

Отличие от томографии:

КОГДА ПРИМЕНЯТЬ

• После томографии, выявившей структурные проблемы
• При переименовании папок/файлов с обновлением ссылок
• При слиянии дублирующихся документов
• При рефакторинге именования (устаревшие конвенции → новые)

АРТЕФАКТЫ

Входные:
- Отчёт томографии (или аудита)
- Текущее состояние репозитория

Рабочие (в tmp/):
- PLAN.md — маппинг: было → стало для каждого файла
- PROGRESS.md — статус каждого сеанса
- scan.sh — поиск ссылок по репозиторию
- validate.sh — проверка отсутствия битых ссылок

Выходные:
- Изменения в репозитории (серия коммитов с тегами)
- PLAN.md с отметками ✅ переносится в arh/

ФАЗЫ

Фаза 0 — Фиксация

git tag rehab-YYYY-MM-start

Создать маппинг в tmp/PLAN.md. Каждый файл должен получить статус:
- RENAME — переименовать/переместить
- CREATE — создать новый
- DELETE — удалить
- ARCHIVE — перенести в arh/
- KEEP — оставить как есть
- REVIEW — требует ручного решения

Фаза 1 — Создание недостающего

Создать новые файлы которых не было. Коммит: rehab: create missing files.

Правило: Сначала создать, потом переносить/удалять — новое должно существовать
до того как старое исчезает.

Фаза 2 — Миграция

Атомарное правило: переименование файлов и обновление всех ссылок на них —
ОДИН коммит. Нельзя разделять: между переносом и обновлением ссылок
репозиторий в неконсистентном состоянии.

# Переименовать
git mv old/path.md new/path.md

# Обновить все ссылки во всём репозитории
find /opt/claude-workspace -name "*.md" -exec sed -i 's|old/path|new/path|g' {} +

# Проверить что ноль вхождений старого пути
grep -rn 'old/path' --include="*.md" | wc -l  # должно быть 0

# Коммит
git commit -m "rehab: migrate [описание]"

Область поиска: весь репозиторий, не только изменяемая папка.

Фаза 3 — Очистка

Удалить или архивировать устаревшее. Коммит: rehab: cleanup [описание].

Правило: Удалять только после того как:
1. Новый файл существует (создан в фазе 1 или перенесён в фазе 2)
2. Все ссылки на старый файл обновлены

Фаза 4 — Верификация

Запустить validate.sh. Все проверки должны пройти:

✅ Ноль ссылок на старые пути
✅ Все файлы из PLAN.md имеют статус ✅
✅ Каждая папка-аспект имеет README.md
✅ git log --follow показывает историю для перенесённых файлов

После верификации:

git tag rehab-YYYY-MM-end
mv tmp/PLAN.md architect/arh/rehab-YYYY-MM-plan.md

СЕАНСЫ

Каждый сеанс = один git commit. Именование коммитов:

rehab: rename folders 1-9 (N references updated)
rehab: migrate UPPERCASE files to aspects
rehab: update navigation (CLAUDE.md, INDEX.md)
rehab: cleanup arh/ and stale files

Каждый сеанс обратим: git reset HEAD~1 --hard.

ИНСТРУМЕНТЫ

scan.sh — найти все ссылки на паттерн

#!/bin/bash
PATTERN=${1:-"ваш паттерн"}
grep -rn "$PATTERN" /opt/claude-workspace --include="*.md" | grep -v "^Binary" | sort

validate.sh — проверить нет битых ссылок

#!/bin/bash
ERRORS=0
while IFS= read -r file; do
  while IFS= read -r link; do
    target=$(dirname "$file")/$link
    if [ ! -f "$target" ]; then
      echo "BROKEN: $file -> $link"
      ERRORS=$((ERRORS + 1))
    fi
  done < <(grep -oP '\[.*?\]\(\K[^)]+(?=\))' "$file" | grep -v '^http' | grep '\.md')
done < <(find /opt/claude-workspace/architect -name "*.md" | grep -v arh/ | grep -v tmp/)
echo "Total broken links: $ERRORS"

СВЯЗАННЫЕ ДОКУМЕНТЫ

• guidance/tools/documentation-tomography.md — диагностика
• naming/naming-files.md — стандарт именования
• policy/policy-code-data-separation.md — что в git

Версия: 1.0.0
Дата: 2026-03-30