Pr Semantic Verifier

Проверка Семантики PR

Запуск Навыка

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

Применяю экспериментальный навык «Проверка семантики PR» (обратная связь — @kir-kopylov): <кратко назовите конкретную пользу для текущего запроса>; продолжаю без ожидания.

Не включайте в строку author_github, внутреннее имя папки или пересказ всего запроса. Не спрашивайте, применять ли навык.

Если одновременно подходят совместимые навыки, выберите минимальный набор и покажите одну общую строку. Если подходы ведут к несовместимым результатам и запрос не позволяет выбрать, спросите только о желаемом результате, не о разрешении применить навык.

Запуск навыка не расширяет полномочия. Выполните всю безопасную и уже разрешённую часть; запросите подтверждение только непосредственно перед ещё не разрешённым внешним или изменяющим действием. Не запрашивайте повторно уже данное разрешение и не дублируйте системное окно подтверждения.

Обзор

Skill проверяет логическую цепочку:

обещание PR → прямое наблюдаемое следствие → доказательства → base/head → semantic_verdict.

Он не считает зелёный CI доказательством сам по себе и не принимает падающий тест за дефект реализации, пока не проверена семантика теста. Базовый режим строго read-only: диагностировать, назвать границу доказанного и передать следующий узкий scope.

Версия v1 работает с GitHub PR. Для GitLab MR используйте отдельный provider-aware workflow.

Входы И Источник Требования

Зафиксируйте:

• репозиторий, PR и точные base SHA / head SHA;
• заявленный результат и целевую поверхность;
• источник требования;
• доступные проверки, логи и наблюдения с их временем;
• какие слои обещаны: repository, local-test, CI, review, merge, installation, runtime, user-outcome.

Нормативный порядок источников:

intent_contract:
  priority:
    - user-goal
    - issue-or-spec
    - pr-body
  evidence_only:
    - code
    - tests
  conflict_action: ask-one-question

Применяйте его так:

1. явная цель пользователя;
2. acceptance criteria связанной issue или спецификации;
3. описание PR;
4. код и тесты — доказательства реализации, но не источник намерения.

Если первые три источника существенно противоречат друг другу, задайте один вопрос и не придумывайте критерий самостоятельно.

Процесс

1. Прочитайте known-exceptions.yaml и примените совпавшее do_next_time.
2. Проверьте фактические repo, PR, base/head и текущий head SHA. Не анализируйте «примерно тот же» commit.
3. Сформулируйте одно или несколько существенных утверждений PR и целевую поверхность каждого.
4. Откройте references/verdict-model.md. Для каждого утверждения заполните claim/evidence ledger и укажите свежесть доказательств.
5. Для каждого теста ответьте:
   • Может ли тест пройти, когда обещанный результат всё ещё сломан?
   • Может ли тест упасть, хотя реализация соответствует исходному требованию?
6. Отделите прямое наблюдение от proxy. Наличие файла, строки, mock, config или зелёного job не переносит доказательство на installation, runtime или пользовательский результат.
7. Если причинность падения спорна, откройте references/base-head-attribution.md и сравните один сценарий в двух независимых временных копиях. Не переключайте dirty worktree пользователя.
8. Отдельно проверьте изменения теста, fixture, config, lockfile, зависимостей и критерия успеха. Base/head не устанавливает правильность test oracle.
9. Назначьте один общий semantic_verdict и все подходящие finding_types по references/verdict-model.md.
10. Назовите верхний доказанный слой, непроверенные слои, следующего владельца и одно следующее действие.

Если необходимое наблюдение относится к внешнему UI или компьютеру другого человека, индексная страница, старый лог или локальный repo не являются live-подтверждением. Оставьте слой UNVERIFIED, пока не получено наблюдение на этой поверхности.

Формат Результата

Целевое утверждение:
Целевая поверхность:
Источник требования:
Base SHA:
Head SHA:
Свежесть доказательств:

Semantic verdict:
Finding types:

Матрица утверждений и доказательств:
- claim:
  essential:
  required_observation:
  available_evidence:
  evidence_freshness:
  proves:
  does_not_prove:
  claim_verdict:

Проверка test oracle (обязательна для каждого теста):
- test:
  questions:
    could-pass-while-broken:
      question: Может ли тест пройти, когда обещанный результат всё ещё сломан?
      answer:
      evidence:
    could-fail-while-correct:
      question: Может ли тест упасть, хотя реализация соответствует исходному требованию?
      answer:
      evidence:

Base/head (если применимо):
- case:
  command_or_scenario:
  base_result:
  head_result:
  environment_comparable:
  attribution:

Верхний доказанный слой:
Непроверенные слои:
Следующий владелец:
Следующее действие:

Правила агрегации:

• любое опровергнутое существенное утверждение → DISPROVED;
• все существенные утверждения подтверждены прямыми наблюдениями → PROVED;
• доказана только часть существенных утверждений → PARTIAL;
• имеются лишь косвенные зелёные признаки → PROXY_ONLY;
• сопоставимого прямого доказательства нет → UNVERIFIED.

Read-Only Граница И Handoff

Структурированный блок ниже нормативен для mutation-прав:

mutation_policy:
  verification:
    mode: read-only
    allowed:
      - read
      - run-focused-checks
      - temporary-artifacts
    prohibited:
      - edit-tracked-files
      - rerun-ci
      - comment
      - commit
      - push
      - merge
      - release
    result: report-only
  explicit-fix:
    sequence:
      - verdict
      - handoff
    execution: specialized-workflow
    prohibited:
      - silent-mutation

В режиме проверки разрешено читать metadata, diff, checks, логи, требования, код и тесты, запускать доверенные focused checks и создавать временные build/cache artifacts.

Без явной просьбы исправить запрещено:

• менять код, тесты, snapshots, PR body или tracked-файлы;
• переключать ветки рабочего repo или менять refs;
• перезапускать CI;
• писать комментарии, resolve threads, approve или merge;
• делать commit, push, release или deployment.

Если пользователь прямо попросил «исправь», сначала завершите semantic verdict, затем передайте узкий scope:

• корректный падающий GitHub Actions check → gh-fix-ci;
• замечания review → gh-address-comments;
• ветка, push, PR, merge и cleanup → provedenie-vetki-do-uborki;
• создание или изменение team skill → dobavlenie-navyka-v-biblioteku;
• ошибочная архитектурная предпосылка → razgrom-plana-na-naivnost;
• повторяющийся цикл без изменения результата → peresmotr-predposylok-posle-povtora.

Не получайте mutation-права из слов «проверь», «разбери» или «объясни».

Eval Gate

Текущий статус — experimental. Перед повышением до team-ready проведите независимую оценку по references/eval-rubric.md. Зелёный repo CI подтверждает структуру контракта, но не качество рассуждения и не меняет evaluation.status: not-run.

Границы

Не используйте skill:

• для общего code review стиля, безопасности или архитектуры без конкретного утверждения PR;
• вместо gh-fix-ci, когда корректный падающий check уже локализован;
• для публикации, merge или branch cleanup;
• для утверждения о текущем состоянии внешней машины без свежего наблюдения;
• для GitLab MR в v1.

Нельзя ослаблять исходный инвариант, удалять проверку или добавлять skip только ради зелёного CI.

Опрос После Использования

Опрос задаётся один раз — после выдачи semantic verdict и handoff либо после честного стопа, не посреди проверки. Если пользователь уже ответил «пропустить» в этой сессии, не переспрашивайте.

Опрос по skill:
1. Что в этом использовании pr-semantic-verifier было полезно?
2. Что стоит доработать в skill или его формате?
Можно ответить коротко или написать "пропустить".

Если пользователь ответил, сохраните санированную карточку в ~/.codex/skill-runs/pr-semantic-verifier/usage-feedback.jsonl — лучше через bundled script:

python3 scripts/log_usage_feedback.py --liked "..." --improve "..." --outcome "..."

Script перед записью редактирует приватные пути, контакты и token-like строки и сохраняет в JSONL redaction_applied и redaction_types. Если запись невозможна из-за sandbox, прав или отсутствия tools, не делайте вид, что лог сохранён: скажите об этом и покажите короткую JSONL-карточку для ручного сохранения. Raw-ответы, контакты, пути и секреты не коммитить.

Логирование Сбоев

Перед выполнением прочитайте локальный known-exceptions.yaml как список уже известных случаев и применяйте подходящее do_next_time без нового поиска.

Если пользователь поправил skill, tool/API упал, нарушена read-only граница, test oracle оказался неверным или skill перенёс доказательство между слоями, запишите приватную карточку в ~/.codex/skill-runs/pr-semantic-verifier/exception-log.jsonl.

Пишите факты: что skill хотел доказать, какие данные видел, где ошибся, какая предпосылка была ложной и что сделать в следующий раз. Если поле неизвестно, пишите unknown. Raw logs не коммитить.

Definition Of Done

Проверка завершена, когда:

• зафиксированы точные PR, base/head и целевое утверждение;
• каждый существенный claim связан с требуемым прямым наблюдением;
• test oracle проверен двумя контрвопросами;
• спорная причинность либо проверена сопоставимым base/head, либо оставлена неизвестной;
• verdict не переносит доказательство на более высокий слой;
• read-only граница соблюдена;
• указан один следующий владелец и одно следующее действие.