update-index

name

update-index

description

Обновление и верификация индекса документов судебного дела. Используй, когда юрист говорит «обнови индекс», «проверь целостность дела», «синхронизируй файлы с индексом», «я вручную добавил/удалил/переместил файлы», «проверь, всё ли на месте», «актуализируй реестр», «какие файлы не в индексе». Также используй автоматически после ручных операций с файлами, когда состояние файловой системы могло разойтись с index.yaml. НЕ используй для приёма новых материалов (это intake/add-evidence/add-opponent) или генерации таблицы (это catalog).

Update-Index — Обновление и верификация индекса

Скилл работает по контракту preview → confirm → apply → verify. Оркестрацию ведёт main-Sonnet: он сам читает .vassal/index.yaml, сканирует файловую систему, создаёт/удаляет md-зеркала, обновляет .vassal/history.md и архивирует лог прогона. При большом числе документов (ориентир: >30 затронутых записей) main-Sonnet может опционально делегировать Haiku-subagent только механические grep/YAML-сводки по контракту 3.3A из shared/subagent-dispatch.md, но все записи в файлы дела делает только main-Sonnet.

Предусловия

• Существуют .vassal/index.yaml и .vassal/case.yaml.
• Установлены зависимости для extract_text.py. Если [PLUGIN_ROOT]/scripts/setup.sh на этой машине ещё не запускался — запусти его один раз.
• Для опционального массового помощника доступен Task(model=haiku), но отсутствие Haiku-subagent не блокирует update-index: main-Sonnet может довести скилл до конца самостоятельно.

Переменные сессии

Вычисли один раз в начале прогона:

• run_timestamp = текущее локальное ГГГГ-ММ-ДД-ЧЧмм
• next_id_hint = текущее next_id из .vassal/index.yaml (если поля нет — считай 1)

Фаза 1 — Preview (main-Sonnet)

Вызови скрипт для получения состояния:

python3 "$PLUGIN_ROOT/scripts/scan_case_state.py" "$CASE_ROOT"

Распарси JSON: new_files (новые файлы), orphans (записи без файла), stale_mirrors (устаревшие зеркала), index_count, fs_count.

Покажи Сюзерену превью целиком: сколько документов в индексе, сколько файлов на диске, и три списка по режимам A/B/C.

ЗАПРЕЩЕНО на preview-фазе: любые записи на диск, mkdir, cp, rm, запуск extract_text.py.

Фаза 2 — Confirm

1. Дождись явного решения Сюзерена по каждому классу изменений:
   • режим A: какие новые файлы добавить в индекс;
   • режим B: какие orphans удалить и у каких записей обновить путь;
   • режим C: какие зеркала пересоздать.
2. Если решение неполное или двусмысленное, пересобери preview и запроси уточнение.
3. Если Сюзерен отменил действие — остановись без изменений.

Фаза 3 — Apply (main-Sonnet)

Выполняй только явно подтверждённый diff-план. Любая неоднозначность = остановка без побочных изменений.

Режим A — Добавить новые файлы

1. Для каждого подтверждённого нового файла возьми следующий doc-ID строго из next_id_hint / next_id в .vassal/index.yaml.
2. Для каждого файла используй точный цикл извлечения текста:

   TMP=$(mktemp -d -t vassal-update-index-XXXXXX)
   trap 'rm -rf "$TMP"' EXIT
   OCR_JSON="$TMP/extract.json"
   python3 "$PLUGIN_ROOT/scripts/extract_text.py" "$file" --output-dir "$TMP" > "$OCR_JSON"
   

   Перед OCR обязательно приведи file к каноническому пути и проверь, что он резолвится внутри корня дела; если путь уводит чтение за пределы case root, останови apply для этого файла. Затем прочитай saved_to из JSON-вывода extract_text.py и используй именно этот путь к .txt. Если нужен ожидаемый <stem>, считай его строго как Path(filepath).stem в Python, то есть имя файла без последнего суффикса. Перед подготовкой зеркала обязательно проверь, что extract_text.py завершился с exit 0, saved_to присутствует, резолвится внутри текущего $TMP, оканчивается на .txt и указывает на обычный файл. Если любой из этих пунктов не выполнен, прерви apply для данного файла без записи зеркала и без добавления записи в индекс; молча считать тело пустым запрещено.
3. Сначала собери candidate-зеркало в $TMP по шаблону из shared/mirror-template.md: frontmatter должен отражать будущую запись индекса, а тело зеркала — полный извлечённый текст без усечения по страницам или символам. Не публикуй зеркало в .vassal/mirrors/ до успешного коммита индекса.
4. Добавь запись в candidate-версию .vassal/index.yaml для нового документа. Минимально зафиксируй:
   • id, title, date, type, source, file, mirror;
   • origin (name, date, batch: update-index-YYYY-MM-DD);
   • extraction_method, confidence;
   • mirror_stale: false.
5. Применяй изменения атомарно: держи исходный index.yaml и staged-зеркало в $TMP, валидируй candidate-YAML, затем атомарно замени .vassal/index.yaml; только после успешного коммита индекса атомарно опубликуй staged-зеркало в .vassal/mirrors/doc-NNN.md. Если запись индекса не закоммитилась, зеркало публиковать запрещено. Если публикация зеркала после коммита индекса всё же не удалась, немедленно откати .vassal/index.yaml к предшествующему состоянию.
6. Cleanup временного каталога обязан происходить в любом исходе через trap; отдельный rm -rf "$TMP" на happy-path не считается достаточным.

Режим B — Разрулить orphans

1. Для каждой orphan-записи исполни только подтверждённое решение Сюзерена.
2. Если решение — удалить запись, удали её из .vassal/index.yaml и удали соответствующее зеркало.
3. Если решение — обновить путь, измени только поле file на подтверждённый новый путь.
4. Ничего не удаляй и не перепривязывай по собственной инициативе.

Режим C — Пересоздать устаревшие зеркала

1. Для каждого подтверждённого doc-ID возьми путь к исходнику из поля file соответствующей записи .vassal/index.yaml.
2. Для каждого такого файла используй тот же точный цикл полного re-OCR:

   TMP=$(mktemp -d -t vassal-update-index-XXXXXX)
   trap 'rm -rf "$TMP"' EXIT
   OCR_JSON="$TMP/extract.json"
   python3 "$PLUGIN_ROOT/scripts/extract_text.py" "$file" --output-dir "$TMP" > "$OCR_JSON"
   

   Перед OCR обязательно приведи file из .vassal/index.yaml к каноническому пути и проверь, что он резолвится внутри корня дела; запись, уводящая чтение за пределы case root, считается ошибкой apply. Затем прочитай saved_to из JSON-вывода extract_text.py и используй именно этот путь к .txt. Если нужен ожидаемый <stem>, считай его строго как Path(filepath).stem в Python, то есть имя файла без последнего суффикса. Перед подготовкой нового тела зеркала обязательно проверь, что extract_text.py завершился с exit 0, saved_to присутствует, резолвится внутри текущего $TMP, оканчивается на .txt и указывает на обычный файл. Если любой из этих пунктов не выполнен, не перезаписывай существующее зеркало, не выставляй запись как свежую и останови apply с ошибкой для этого doc-ID.
3. Сначала собери candidate-зеркало и candidate-версию записи индекса в $TMP; до успешного коммита индекса не перезаписывай существующее зеркало.
4. Обнови в candidate-записи .vassal/index.yaml минимум следующие поля:
   • extraction_method и confidence по текущему результату извлечения;
   • last_verified = текущая дата;
   • mirror_stale: false.
5. Применяй изменения атомарно: staged-копию index.yaml провалидируй и атомарно замени только при успешной записи; staged-зеркало публикуй атомарной заменой только после успешного коммита индекса. Если коммит индекса не удался, старое зеркало должно остаться нетронутым. Если замена зеркала после коммита индекса не удалась, сразу откати index.yaml и сохрани прежнее зеркало.
6. Cleanup временного каталога обязан происходить в любом исходе через trap; отдельный rm -rf "$TMP" на happy-path не считается достаточным.

Общая дисциплина apply

1. После завершения apply запиши краткую строку в .vassal/history.md.
2. После любого непустого apply-прогона проверь, что .vassal/index.yaml читается:

   python3 -c "import pathlib, yaml; yaml.safe_load(pathlib.Path('.vassal/index.yaml').read_text(encoding='utf-8'))"
   

3. Не создавай временные OCR-артефакты вне mktemp-каталога и не оставляй их после завершения шага.

Фаза 4 — Verify (main-Sonnet)

1. Снова прочитай .vassal/index.yaml и проверь, что все затронутые surviving-записи читаются и указывают на существующие file/mirror.
2. Для всех затронутых документов выставь ocr_quality/ocr_quality_reason через единый скрипт:
   • вызови python3 "$PLUGIN_ROOT/scripts/classify_ocr_quality.py" --extraction-method <extraction_method> --confidence <confidence> --total-chars <total_chars> --pages <pages> и подставь результат в поля. Если total_chars или pages неизвестны или отсутствуют, передавай значение "" или "null" — скрипт обработает их как None и не упадёт.
3. Для update-index, если отдельный /vassal-litigator-cc:reocr не запускался, фиксируй ocr_reattempted: false.
4. Для записей с ocr_quality: ok всегда ставь ocr_quality_reason: "". Если качество low или empty, не скрывай это в резюме: перечисли doc-ID и причину ручной проверки.
5. Проверь, что:
   • новые зеркала созданы, а пересозданные зеркала обновлены;
   • для режима C mirror_stale: false;
   • удалённые orphan-записи действительно исчезли из индекса.
6. Покажи Сюзерену итог: сколько файлов добавлено (режим A), сколько orphan-решений применено (режим B), сколько зеркал пересоздано (режим C), сколько записей получили ocr_quality low/empty.

Идемпотентность

Повторный запуск безопасен: если запись уже синхронизирована и зеркало не устарело, повторно создавать её не нужно.

Граничные случаи

• Файл переименован вручную: старая запись становится orphan, новое имя — новым файлом. Предложи Сюзерену либо обновить путь в режиме B, либо подтвердить две отдельные операции.
• Если после extract_text.py отсутствует saved_to, saved_to резолвится вне текущего $TMP, не оканчивается на .txt или файл по этому пути не является обычным файлом, считай это ошибкой apply, а не допустимым пустым зеркалом: в режиме A не добавляй запись, в режиме C сохраняй старое зеркало и не помечай запись как свежую; обязательно сообщи агенту/пользователю причину сбоя.
• Если путь file из preview-плана или из .vassal/index.yaml после каноникализации уводит чтение за пределы case root, считай это ошибкой apply и не запускай extract_text.py для такой записи.
• Если в индексе есть legacy-записи v0.5.x без ocr_quality, а они попали в режим B/C, после verify заполни им ocr_quality по презумпции из shared/conventions.md.