# Run Pack Spec V1

Дата: 2026-04-02  
Назначение: единый структурный контракт для run-артефактов Address Query.

## 1. Обязательная структура папки

Путь:

- `docs/ADDRESS/runs/<run_id>/`

Обязательные файлы:

1. `run_summary.json`
2. `full_live_results.json`
3. `failures_only.json`
4. `README.md`

Отсутствие любого из файлов = run-pack невалиден для gate.

## 2. Минимальные поля run_summary.json

### 2.1 Top-level

1. `run_id`
2. `generated_at` (или `date` для legacy)
3. `source_questions_file`
4. `strict_policy`
5. `totals` (object)

### 2.2 `totals`

1. `questions_total`
2. `semantic_pass_count`
3. `route_pass_count`
4. `strict_pass_count`
5. `factual_count`
6. `partial_coverage_count`
7. `http_error_count`

Рекомендуется (если есть):

1. `route_pass_rate`
2. `strict_pass_rate`
3. `execution_error_count`
4. `false_factual_count`
5. `false_factual_rate`

## 3. Минимальные поля full_live_results.json

Top-level:

1. `run_id`
2. `rows` (array)

Для каждой строки `rows`:

1. `id` (или `case_id`)
2. `question`
3. `reply_type` (или `assistant_reply_type`)
4. `actual_intent` (или `detected_intent`)
5. `selected_recipe`
6. `route_pass`
7. `strict_pass`
8. `mcp_call_status` (или `execution_status`)
9. `limited_reason_category` (если partial/limited)
10. `debug_payload`

## 4. Минимальные поля failures_only.json

Файл должен быть JSON array.

Рекомендуемые поля элемента:

1. `id` (или `case_id`)
2. `question`
3. `failure_type`
4. `expected`
5. `actual`
6. `diagnostic_summary`
7. `recommended_fix_owner`

## 5. README.md run-пака должен содержать

1. цель прогона
2. используемый question set
3. команду запуска
4. итоговые метрики
5. список известных отклонений (если есть)
6. решение: `promote | fix_required`

## 6. Gate Rules

Domain gate:

1. `strict_pass(route)=100%`
2. `false_factual_rate=0`
3. `execution_error_rate=0`

Global gate:

1. baseline stress не ниже эталона
2. baseline follow-up не ниже эталона
3. нет роста `execution_error_count`

## 7. Автоматические проверки

Structural validator:

- `python scripts/validate_address_run_pack.py docs/ADDRESS/runs/<run_id>`

Baseline comparator:

- `python scripts/compare_address_run_summary.py --baseline-summary <baseline_run_summary.json> --candidate-summary <candidate_run_summary.json>`

Nightly regression orchestrator:

- `python scripts/run_address_nightly_regression.py`

Windows wrapper:

- `powershell -ExecutionPolicy Bypass -File .\scripts\run_address_nightly_regression.ps1`

## 8. Сопровождающие обновления docs

После успешного run-пака обновляются:

1. `runtime_readiness_matrix_v1.md`
2. `address_scenario_matrix.md`
3. `global_execution_checklist_v1.md`
4. `stage_closeout_*.md` (для крупных этапов)