# Strict Project Governor v0.2

**ДА — узкую версию стоит продолжить до пользовательского пилота.** Этот MVP проверяет точные project-state правила, а не смысл произвольного ответа. Реальный парный API-прогон выполнен; результат — [RESULTS.md](RESULTS.md).

## Быстрый запуск

**Расширение Chrome / Edge:** распакуйте архив, откройте `chrome://extensions` или `edge://extensions`, включите режим разработчика, нажмите «Загрузить распакованное» и выберите папку **extension**. Нажмите значок расширения. Node.js для этого режима не нужен. Фактическая загрузка MV3 протестирована в Edge; панель отдельно протестирована в Chrome. Автоматическую установку расширения в Chrome не заявляем проверенной.

**Веб-версия:** Node.js 22+; без установки зависимостей:

```text
npm start
```

Откройте `http://127.0.0.1:4174`. В Windows можно открыть START.cmd. Сервер доступен только на этом компьютере. Веб-версия и расширение имеют отдельные локальные базы. Версия 0.1 сохранена отдельно, её база не изменяется.

## Что именно проверяем

- Принятое значение: `storage` должно быть ровно `local`.
- Числовой максимум: `budget` не больше `100`, единица ровно `USD`.
- Запрещённые варианты: `acquisition` не может быть `scraping` или `purchased_list`.
- Все поля обязательны. Строки выбираются из закрытого словаря `choices`; неизвестный синоним не считается разрешённым вариантом.
- Типы, регистр, проект и ревизия должны совпадать. Приведение строк к числам и пересчёт единиц не выполняются.
- В v0.2 числа — целые единицы в пределах ±10^12. Для денег с дробной частью используйте поле в центах с соответствующей единицей и лимитом. Дроби и экспоненциальная запись отклоняются, чтобы не округлить нарушение в допустимое значение. Максимум сам по себе не задаёт нижнюю границу: если требуется ограниченный набор чисел, перечислите его в choices.

Три результата:

| Результат | Значение | Accept |
|---|---|---|
| PASS | Все заявленные поля соответствуют текущим правилам | Доступен |
| BLOCK | Найдено хотя бы одно конкретное нарушение | Недоступен |
| NEEDS_INPUT | Не хватает данных или нарушен контракт | Недоступен |

Если одновременно есть известное нарушение и пропущенное поле, результат BLOCK содержит и нарушение, и недостающие данные. Некорректный JSON, повтор ключа, лишние поля и несколько значений одного поля не получают PASS.

## Рабочий цикл

1. Укажите имя и создайте проект с примерами. Откройте «Изменить правила», настройте поля и допустимые значения. Это технический прототип: редактор правил пока JSON, не конструктор форм.
2. Укажите причину изменения, просмотрите State Diff и подтвердите. Ревизия увеличится; предыдущие правила и причина останутся в истории. В v0.2 операции Accept/Reject/Constraint над правилами представлены полями `equals`, `forbidden` и `max` в одном редакторе diff.
3. Введите задачу, нажмите «Собрать запрос», вручную перенесите его в выбранный ИИ. Next собирает запрос следующего плана. Весь набор правил включается полностью, без скрытого сокращения.
4. Вставьте полученный JSON и нажмите «Проверить». Можно начать с двух встроенных примеров. Critic формирует запрос исправления на основании найденных ошибок; модель из расширения не вызывается.
5. При PASS нажмите Accept. Механизм принятия повторно проверит предложение и текущую ревизию **в момент записи**, затем сохранит JSON в журнале. Предыдущее зелёное состояние не позволяет принять изменённый текст или предложение по устаревшим правилам.

**Accept не запускает внешний код, не отправляет сообщения и не изменяет Canonical State.** Он фиксирует предложение в локальном журнале. Проверяется только JSON-контракт: если ИИ написал `storage=local`, но в отдельном коде отправил данные на сервер, эта версия этого не обнаружит. Принятое предложение действительно относительно записанной ревизии, а не всех будущих правил.

## Данные

Только `storage` permission, без host permissions, content scripts, чтения страниц, cookies, приватных endpoints, сетевых запросов или API-ключей. CSP запрещает connect. Выделение/копирование на странице чата выполняет сам пользователь; панель принимает ввод.

До 20 проектов, 40 полей на проект, 1000 пересмотров правил, 500 принятых предложений суммарно, 1.5 млн символов базы. При достижении лимита запись прекращается без скрытого удаления истории. JSON предложения — до 50 000 символов. Импорт состояния — до 1.5 млн символов, с проверкой схемы, истории и коллизий ID. Данные открытым текстом в профиле браузера, без шифрования и синхронизации. Это не защита от владельца профиля или вредоносного ПО.

«Экспорт состояния» сохраняет **правила и историю их изменений**, но не журнал принятых предложений. Журнал виден в панели; в этом тестовом выпуске переноса его между профилями нет. Удаление проекта удаляет и его журнал. Не выдаём этот ограниченный экспорт за полную резервную копию.

## Проверки

```text
npm test
npm run benchmark
node benchmark/ablation.mjs
```

173 автоматических теста; 150 из них — матрица контрактных случаев. Браузерные сценарии прошли для веб-панели в Chrome и MV3 в Edge. `tests/ui.mjs` требует Playwright только для разработки; runtime расширения не имеет внешних зависимостей. Для браузерных тестов запустите веб-сервер, установите Playwright отдельно и используйте:

```text
npm run test:ui
```

Переменные разработки: `PLAYWRIGHT_MODULE` — абсолютный путь к index.mjs Playwright; `BROWSER_EXECUTABLE` — путь к Chrome/Edge; `EXTENSION_TEST=1` — реальная загрузка MV3 вместо localhost; `GOVERNOR_TEST_WORK` — папка временных тестовых профилей вне поставки.

## Реальный benchmark

`reports/live` содержит **48 реальных API-ответов**, 24 пары, 3 домена, по 48 сообщений общей истории перед финальной задачей. Два повтора каждого из 12 случаев, один snapshot `gpt-4.1-mini-2025-04-14`, temperature 0, одинаковая схема вывода и одинаковая история между режимами. Различается финальный запрос: обычная задача либо задача с компилированным текущим состоянием. Истории созданы для теста, ответы получены от API.

Vanilla: **5/24** ответов нарушили правила (13 отдельных нарушений). Governor: **0/24**. Отдельный post-flight replay реальных vanilla-ответов остановил все пять ошибочных предложений и пропустил все 19 корректных. Это разные измерения — эффект pre-flight и проверка точки принятия. Двойного счёта предотвращённых ошибок нет.

Повторный запуск `npm run benchmark:live` использует сохранённые ответы. Для нового платного прогона сначала скопируйте пакет в отдельную папку и перенесите её `reports/live` в архив; задайте `OPENAI_API_KEY` в окружении. Скрипт вызывает только официальный OpenAI API, не записывает ключ, сохраняет каждый результат, не выбирает «удачные» ответы и останавливается при auth/quota ошибках. Локальный оценочный предел $1 и максимум 48 запросов. Старые результаты не смешиваются с новым набором по хэшу случаев. Подробный протокол — [docs/EXPERIMENT.md](docs/EXPERIMENT.md).

Реальные пользовательские предотвращения и re-explanations avoided ещё не измерены. Результаты одного небольшого стресс-теста не доказывают рыночную ценность. Следующий шаг — контролируемый пилот, а не запуск универсального SaaS.

## Файлы

- `extension/core/strict.mjs` — схема, строгий JSON parser, checker, compiler, diff, acceptance.
- `extension/core/store.mjs` — сериализованная запись, повторная проверка при принятии.
- `canonical-state.schema.json`, `proposal.schema.json` — машиночитаемые контракты; дополнительные инварианты описаны выше.
- `reports/offline.json` — 150 контрактных случаев.
- `reports/live/summary.json` — модель, usage, все ответы и независимый от checker подсчёт.
- `reports/ablation.json` — post-flight-only replay на реальных ответах.
- `reports/ui-web.json`, `reports/ui-extension.json` — результаты браузерных проверок.

Правовой маршрут сохраняет вывод v0.1: ручной ввод в extension; API — только отдельный исследовательский runner. Основания и границы: [docs/EXPERIMENT.md](docs/EXPERIMENT.md). Публикация расширения и OpenAI/MCP-интеграция не выполнялись.