NODEDC_1C/docs/ADDRESS/address_query/run_pack_spec_v1.md

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 (для крупных этапов)